@bongos/core 1.21.182 → 1.22.2

package/tests/hall_reading_world.mjs

@@ -59,6 +59,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules', 'hall-ui', 'public');
@@ -429,7 +430,7 @@ test('roadmap\'s two sub-24px controls clear the floor, on both axes', () => {
 // md-reader.js is a browser IIFE that only touches `window` and `location`, so
 // a two-property sandbox is the whole DOM it needs.
 function loadReader() {
-  const sandbox = { window: {}, location: { hostname: 'builders.example.com', href: 'https://builders.example.com/primer' } };
+  const sandbox = { window: { OTB: realOTB() }, location: { hostname: 'builders.example.com', href: 'https://builders.example.com/primer' } };
   vm.createContext(sandbox);
   vm.runInContext(mdReaderJs, sandbox, { filename: 'md-reader.js' });
   return sandbox.window.OTBMdReader;
@@ -644,6 +645,7 @@ async function bootRoadmap({ progress, versions } = {}) {
     },
   };
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     BongosClient: { createClient: () => client },
     __BRANDING__: {}, __MODULES__: { enabled: {} },
     localStorage: { getItem: () => null, setItem() {}, removeItem() {} },

package/tests/hall_reference_world.mjs

@@ -41,6 +41,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules', 'hall-ui', 'public');
@@ -67,7 +68,7 @@ const rule = (css, selector) => {
 
 // md-reader.js is a browser IIFE that only touches `window` and `location`.
 function loadReader() {
-  const sandbox = { window: {}, location: { hostname: 'builders.example.com', href: 'https://builders.example.com/drachmae' } };
+  const sandbox = { window: { OTB: realOTB() }, location: { hostname: 'builders.example.com', href: 'https://builders.example.com/drachmae' } };
   vm.createContext(sandbox);
   vm.runInContext(mdReaderJs, sandbox, { filename: 'md-reader.js' });
   return sandbox.window.OTBMdReader;

package/tests/hall_signout.mjs

@@ -20,6 +20,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const SRC = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/shell.js'), 'utf8');
@@ -66,6 +67,7 @@ function driveClick({ page = 'settings', href } = {}) {
   };
 
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: {} },
     BongosClient: { createClient: () => api },
     matchMedia: () => ({ matches: false, addEventListener() {} }),

package/tests/hall_street.mjs

@@ -487,7 +487,7 @@ test('the page holds the prototype\'s header, the street, the readings and the c
   assert.match(html, /<a class="street-mark" id="streetHome" href="\/builders\/city"[^>]*>\{\{productName\}\}</);
   for (const id of ['hudNeeds', 'hudMoving', 'hudShare', 'streetMode', 'streetSigns', 'streetPins', 'streetDoors', 'streetCard']) assert.match(html, new RegExp(`id="${id}"`), id);
   const scripts = [...html.matchAll(/<script src="\/builders\/([a-z-]+)\.js/g)].map((m) => m[1]);
-  assert.deepEqual(scripts.filter((s) => !/^street-(deck|office)$/.test(s)), ['shell-trail', 'craft-mode', 'shell', 'palette', 'gov-living', 'gov-feeds', 'city-draw', 'street-draw', 'street-card', 'street-inside', 'street-depth', 'street-desk', 'street-amend', 'street'], 'the hall shell (task 1004544), the living model and its one reader (task 1004685: city-draw.js counts with it, so it loads first), the shared kit, then the card (task 1004528), the interiors (task 1004526), the living street\'s exterior (street-depth.js), the floor desk (task 1004558) and the drafted amendment (task 1004530); the deck rides beside them');
+  assert.deepEqual(scripts.filter((s) => !/^street-(deck|office)$/.test(s)), ['dom-utils', 'shell-trail', 'craft-mode', 'shell', 'palette', 'gov-living', 'gov-feeds', 'city-draw', 'street-draw', 'street-card', 'street-inside', 'street-depth', 'street-desk', 'street-amend', 'street'], 'the hall shell (task 1004544), the living model and its one reader (task 1004685: city-draw.js counts with it, so it loads first), the shared kit, then the card (task 1004528), the interiors (task 1004526), the living street\'s exterior (street-depth.js), the floor desk (task 1004558) and the drafted amendment (task 1004530); the deck rides beside them');
   assert.equal(City.STREET_HREF, '/builders/street', 'the city\'s door is this page');
 });
 

package/tests/hall_studio_world.mjs

@@ -17,6 +17,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -271,7 +272,7 @@ async function bootStudio({ reviews = [], shipped = {}, rank = 'metic', flags =
   const handlers = [];
   const window = {
     BongosClient: { createClient: () => ({ request }) },
-    OTB: {
+    OTB: { ...realOTB(),
       // task 1003936 — the role axis vocabulary (dom-utils OTB.role*). PRESENT for
       // the same reason categoryChip is: an undefined helper throws mid-render.
       roleAxisLabel: () => 'Role',
@@ -574,6 +575,7 @@ function bootShell() {
   };
   const location = { hostname: 'builders.cloudbongos.com', origin: 'https://builders.cloudbongos.com', pathname: '/studio', hash: '', assign() {}, replace() {} };
   const window = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: {} },
     BongosClient: { createClient: () => ({ request: () => new Promise(() => {}) }) },
     matchMedia: () => ({ matches: false, addEventListener() {} }),

package/tests/hall_tweak_editor.mjs

@@ -19,7 +19,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
-import { makeRunner, makeEl, parseInto, walk, settle } from './helpers.mjs';
+import { makeRunner, makeEl, parseInto, walk, settle, realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -133,6 +133,7 @@ function bootEditor({ search = '?page=landing:index', answers = {}, stored = {}
     },
   };
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: { identity: { productName: 'Cloud Bongos' } }, __MODULES__: { enabled: {} },
     BongosClient: { createClient: () => client },
     location: { host: 'builders.cloudbongos.com', hostname: 'builders.cloudbongos.com', protocol: 'https:', origin: 'https://builders.cloudbongos.com', href: 'https://builders.cloudbongos.com/builders/tweak-editor', search, pathname: '/builders/tweak-editor', assign: (u) => { out.navigated = u; } },

package/tests/helpers.mjs

@@ -79,6 +79,20 @@ import { Readable } from 'node:stream';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
+// realOTB — the REAL window.OTB from modules/hall-ui/public/dom-utils.js, built in
+// its own sandbox (task 1004876). Hall scripts escape user text through
+// window.OTB.escapeHtml at call time, so a test that loads one of them without the
+// page's dom-utils.js hands it this: `window.OTB = realOTB()` (or spread
+// `escapeHtml: realOTB().escapeHtml` into a partial stub). The real one, never a
+// re-typed escaper, so a test cannot pass against a weaker copy.
+export const DOM_UTILS_JS = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'dom-utils.js'), 'utf8');
+export function realOTB() {
+  const ctx = { window: {}, document: { querySelector: () => null, createElement: () => ({}) } };
+  vm.createContext(ctx);
+  vm.runInContext(DOM_UTILS_JS, ctx, { filename: 'dom-utils.js' });
+  return ctx.window.OTB;
+}
+
 export const SKIP_MARKER = 'HOST-TOPOLOGY-SKIP';
 
 function emitSkip(missing, note) {
@@ -617,7 +631,7 @@ export function bootProfilePage({ signedIn = true, trail = [], roles = ['ideator
       roleOptions: () => [{ value: '', label: '— any —' }, { value: 'engineer', label: 'Engineer' }, { value: 'artist', label: 'Artist' }],
       roleIsUnset: (d) => !d || d === 'unclassified',
       ROLE_UNSET: 'unclassified',
-      escapeHtml: (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c])),
+      escapeHtml: realOTB().escapeHtml, // the real one (task 1004876)
       $: (sel) => documentObj.querySelector(sel),
       fmtNum: (n) => String(n ?? 0),
       fmtDate: (iso) => String(iso ?? '').slice(0, 10),
@@ -729,7 +743,7 @@ export function bootIdeaPage({ idea = null, status = 200, template = null, viewe
     __BRANDING__: {}, __MODULES__: { enabled: {} },
     BongosClient: { createClient: () => client },
     OTB: {
-      escapeHtml: (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c])),
+      escapeHtml: realOTB().escapeHtml, // the real one (task 1004876)
       $: (sel) => documentObj.querySelector(sel),
       fmtDate: (iso) => String(iso ?? '').slice(0, 10),
       toast() {},
@@ -931,6 +945,7 @@ export function bootSkyPage({
   const windowObj = {
     __BRANDING__: {}, __MODULES__: { enabled: {} },
     BongosClient: { createClient: () => client },
+    OTB: realOTB(), // the page loads dom-utils.js first; sky-data.js escapes through it (task 1004876)
     innerWidth, innerHeight, devicePixelRatio: 1,
     matchMedia: () => ({ matches: reduce }),
     localStorage: { getItem: (k) => (k in store ? store[k] : null), setItem: (k, v) => { store[k] = String(v); } },

package/tests/html_escape.mjs

@@ -0,0 +1,149 @@
+// tests/html_escape.mjs — the ONE HTML escaper per side (task 1004876, goal 1000135).
+//
+// The escaper is what keeps a builder's own words (a task title, an idea) from
+// becoming live markup on another builder's screen. ~45 private copies were
+// collapsed onto two: window.OTB.escapeHtml (modules/hall-ui/public/dom-utils.js)
+// in the browser and escapeHtml (src/html-escape.js, re-exported by the module
+// doorway) on the server. These tests pin:
+//   1. both shared escapers escape all five characters, map null/undefined to '',
+//      and agree with each other on every input;
+//   2. the module doorway hands modules the very same function;
+//   3. pages that used to carry a private copy now render user text through the
+//      shared one (a title with <, & and a quote stays text);
+//   4. the fitness check goes red on a third definition, and on a hall page that
+//      loads dom-utils.js after (or deferred behind) the scripts that need it.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import vm from 'node:vm';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const PUB = path.join(ROOT, 'modules', 'hall-ui', 'public');
+
+const { escapeHtml: serverEscape } = require('../src/html-escape.js');
+const guard = require('../scripts/bongos/escape-helper-guard.js');
+
+// Load the real dom-utils.js into a sandbox and hand back its window.OTB.
+function browserOTB() {
+  const sandbox = { window: {}, document: { querySelector: () => null } };
+  vm.createContext(sandbox);
+  vm.runInContext(fs.readFileSync(path.join(PUB, 'dom-utils.js'), 'utf8'), sandbox, { filename: 'dom-utils.js' });
+  return sandbox.window.OTB;
+}
+
+const HOSTILE = `<img src=x onerror="alert('x')"> & "quoted" 'single' a&amp;b`;
+const CASES = [HOSTILE, '', 'plain', 0, 42, -1.5, true, false, null, undefined, '&lt;', '<<>>', "it's", '"'];
+
+test('server escaper escapes all five HTML characters', () => {
+  assert.equal(serverEscape(`<a href="x" title='y'>&</a>`),
+    '&lt;a href=&quot;x&quot; title=&#39;y&#39;&gt;&amp;&lt;/a&gt;');
+});
+
+test('server escaper: null/undefined render as empty text, numbers and booleans as their string', () => {
+  assert.equal(serverEscape(null), '');
+  assert.equal(serverEscape(undefined), '');
+  assert.equal(serverEscape(0), '0');
+  assert.equal(serverEscape(42), '42');
+  assert.equal(serverEscape(false), 'false');
+});
+
+test('server escaper escapes an ampersand first, so an existing entity is shown literally', () => {
+  assert.equal(serverEscape('&lt;'), '&amp;lt;');
+});
+
+test('browser and server escapers agree on every input', () => {
+  const OTB = browserOTB();
+  for (const c of CASES) assert.equal(OTB.escapeHtml(c), serverEscape(c), `input ${JSON.stringify(c)}`);
+});
+
+test('the module doorway exports the shared server escaper', () => {
+  const api = require('../src/module-api.js');
+  assert.equal(api.escapeHtml, serverEscape);
+});
+
+test('a hall helper that dropped its private copy renders user text through window.OTB', () => {
+  // hall-kit.js used to carry its own esc() (exported as OTBKit.esc); it must now delegate, at call time.
+  const sandbox = { window: {}, document: { querySelector: () => null } };
+  vm.createContext(sandbox);
+  vm.runInContext(fs.readFileSync(path.join(PUB, 'dom-utils.js'), 'utf8'), sandbox);
+  vm.runInContext(fs.readFileSync(path.join(PUB, 'hall-kit.js'), 'utf8'), sandbox);
+  const lib = sandbox.window.OTBKit;
+  assert.ok(lib && typeof lib.esc === 'function', 'hall-kit exposes esc');
+  assert.equal(lib.esc('Fix <b> & "q" \'s\''), 'Fix &lt;b&gt; &amp; &quot;q&quot; &#39;s&#39;');
+  assert.equal(lib.esc(null), '');
+});
+
+test('fitness: a third escape table anywhere in the code is a hard fail', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'esc-guard-'));
+  try {
+    fs.mkdirSync(path.join(tmp, 'src'), { recursive: true });
+    fs.mkdirSync(path.join(tmp, 'modules', 'x', 'public'), { recursive: true });
+    fs.mkdirSync(path.join(tmp, 'modules', 'x', 'tests'), { recursive: true });
+    fs.writeFileSync(path.join(tmp, 'src', 'html-escape.js'), "const T = { '<': '&lt;' };\n");
+    fs.writeFileSync(path.join(tmp, 'modules', 'x', 'tests', 't.mjs'), "const T = { '<': '&lt;' };\n");
+    let r = guard.checkOneHtmlEscaper({ root: tmp });
+    assert.equal(r.ok, true, r.violations.join('\n'));
+    // A renamed copy is still caught: the detector reads the table, not the name.
+    fs.writeFileSync(path.join(tmp, 'modules', 'x', 'public', 'page.js'),
+      "const hesc = (s) => String(s).replace(/</g, '&lt;');\n");
+    r = guard.checkOneHtmlEscaper({ root: tmp });
+    assert.equal(r.ok, false);
+    assert.equal(r.hardFail, true);
+    assert.match(r.violations[0], /modules\/x\/public\/page\.js:1/);
+  } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+});
+
+test('fitness: a delegate to the shared escaper is not a copy', () => {
+  assert.deepEqual(guard.findEscapeTables('function esc(s) { return window.OTB.escapeHtml(s); }'), []);
+  assert.deepEqual(guard.findEscapeTables("s.replace(/&lt;/g, '<')"), [], 'a DECODER is not an escaper');
+  assert.deepEqual(guard.findEscapeTables("x\n{ '<': \"&lt;\" }"), [2]);
+});
+
+test('fitness: a local escaper name that does not delegate is a hard fail (the old primer fallback)', () => {
+  const browser = { browser: true };
+  assert.deepEqual(guard.findFakeDelegates("  const escapeHtml = (MD && MD.escapeHtml) || ((s) => String(s));", browser), [],
+    'names the shared one — but the line-level rule cannot see the fallback, so primer.js no longer has one');
+  assert.deepEqual(guard.findFakeDelegates('  const escapeHtml = (s) => String(s);', browser), [1]);
+  assert.deepEqual(guard.findFakeDelegates('  function esc(s) { return s; }', browser), [1]);
+  assert.deepEqual(guard.findFakeDelegates('  function esc(s) { return window.OTB.escapeHtml(s); }', browser), []);
+  assert.deepEqual(guard.findFakeDelegates('  var esc = kit.esc;', browser), []);
+  // server: `esc` is also a regex/markdown escaper name there, so only the HTML names are held
+  assert.deepEqual(guard.findFakeDelegates("const esc = (k) => k.replace(/[.*]/g, '\\\\$&');"), []);
+  assert.deepEqual(guard.findFakeDelegates('const hesc = (s) => String(s);'), [1]);
+  assert.deepEqual(guard.findFakeDelegates("const { escapeHtml: hesc } = require('../../src/html-escape');"), []);
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'esc-guard-'));
+  try {
+    fs.mkdirSync(path.join(tmp, 'modules', 'x', 'public'), { recursive: true });
+    fs.writeFileSync(path.join(tmp, 'modules', 'x', 'public', 'p.js'), 'const esc = (s) => String(s);\n');
+    const r = guard.checkOneHtmlEscaper({ root: tmp });
+    assert.equal(r.ok, false);
+    assert.match(r.violations[0], /p\.js:1 — defines a local HTML escaper name/);
+  } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+});
+
+test('fitness: the guard is registered in fitness.js CHECKS, so CI runs it', () => {
+  const fitness = require('../scripts/bongos/fitness.js');
+  const checks = fitness.CHECKS || fitness.checks;
+  assert.ok(Array.isArray(checks), 'fitness.js exports its CHECKS list');
+  assert.ok(checks.includes(guard.checkOneHtmlEscaper), 'checkOneHtmlEscaper is one of the fitness checks');
+});
+
+test('fitness: a hall page must load dom-utils.js first and synchronously', () => {
+  const ok = '<script src="/builders/dom-utils.js?v=1"></script><script src="/builders/shell.js"></script>';
+  assert.equal(guard.hallPageOrderProblem(ok), null);
+  assert.equal(guard.hallPageOrderProblem('<p>no scripts</p>'), null);
+  assert.match(guard.hallPageOrderProblem('<script src="/builders/shell.js"></script><script src="/builders/dom-utils.js"></script>'), /before/);
+  assert.match(guard.hallPageOrderProblem('<script src="/builders/dom-utils.js" defer></script><script src="/builders/shell.js"></script>'), /defer/);
+  assert.match(guard.hallPageOrderProblem('<script src="/builders/shell.js"></script>'), /never/);
+});
+
+test('fitness: the real tree holds exactly the two shared escapers', () => {
+  const r = guard.checkOneHtmlEscaper();
+  assert.equal(r.ok, true, r.violations.join('\n'));
+});

package/tests/lightbulb.mjs

@@ -17,6 +17,7 @@ import path from 'node:path';
 import vm from 'node:vm';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -265,6 +266,7 @@ function boot({ storage = {}, throwing = false, respond } = {}) {
     ? { ok: true, status: 200, json: { ideas: [{ id: '5', title: '<b>Bold</b> idea', author_name: 'Bo', captured_at: '2026-10-01T00:00:00Z' }] } }
     : { ok: true, status: 201, json: { ideas: [{ id: '801', title: 'Sort drafts' }, { id: '802', title: 'Name writers' }], split_by: 'ai' } }));
   const win = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     location: { pathname: '/studio' },
     localStorage: store,
     fetch: (url, opts) => {

package/tests/module_api.mjs

@@ -20,6 +20,7 @@ const seams = require(path.join(ROOT, 'src', 'module-seams.js'));
 // `withTx` was added; no enabled module at its pinned coreVersion lost a capability.
 const PUBLISHED_SURFACE = [
   'CORE_VERSION',
+  'escapeHtml', // task 1004876: THE server-side HTML escaper (1.22.0) — modules render user text through it, never a private copy
   'requireBuilder', 'requireRank', 'rankMeetsThreshold', 'requireBfgPrincipal', 'allowBoxScope', 'resolveSession',
   'requirePermission', // BV1.R105: the authority-atom gate module routes migrate onto (1.19.0; ADR 0151)
   'requireActAlone', // added by task 1004657 (ADR 0363 D5): a building's own page asks its decision-rules row before one builder acts alone. On the doorway because eight buildings' pages live in six modules and core, and each must refuse the same way People does

package/tests/module_store_howto.mjs

@@ -16,6 +16,7 @@ import os from 'node:os';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -173,7 +174,7 @@ test('a delisted module\'s how-to still reads for people who hold it, and only f
 // ---- the page: the author's markdown is untrusted input ----
 
 function loadReader() {
-  const ctx = { window: {}, location: { href: 'https://builders.example.com/builders/modules', hostname: 'builders.example.com' }, URL };
+  const ctx = { window: { OTB: realOTB() }, location: { href: 'https://builders.example.com/builders/modules', hostname: 'builders.example.com' }, URL };
   vm.createContext(ctx);
   vm.runInContext(fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/md-reader.js'), 'utf8'), ctx);
   return ctx.window.OTBMdReader;

package/tests/modules_external_export_contract.mjs

@@ -0,0 +1,48 @@
+// tests/modules_external_export_contract.mjs — modules/ exports whose callers no
+// code-file scan can see (task 1004891).
+//
+// Task 1004891 un-exported every modules/ export that no other code file names
+// (knip's finding, filtered by countKnipFindings in scripts/bongos/fitness-ratchets.js).
+// Six were deliberately KEPT, because their consumer is a document rather than code:
+//   - gatherInteractionSignals: the bfg scheduled task calls it by path
+//     (`node -e "require('./modules/sessions/bfg').gatherInteractionSignals(...)"`),
+//     so dropping it breaks that routine at run time with no test or scan noticing;
+//   - fieldCatalog, recordPulse, OWNERLESS_CATEGORIES, SOFT_CAP_FRACTION,
+//     CONTROL_PLANE_SHAPES: each module's CLAUDE.md names it as that module's API.
+// This file pins them, so the next dead-export sweep cannot quietly take them.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+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 read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
+
+test('bfg.gatherInteractionSignals stays exported: the bfg scheduled task calls it by path', () => {
+  const skill = read('.claude/scheduled-tasks/bfg/SKILL.md');
+  assert.match(skill, /require\('\.\/modules\/sessions\/bfg'\)/, 'the skill still requires bfg by path');
+  assert.match(skill, /\.gatherInteractionSignals\(/, 'the skill still calls gatherInteractionSignals');
+  const bfg = require(path.join(ROOT, 'modules/sessions/bfg.js'));
+  assert.equal(typeof bfg.gatherInteractionSignals, 'function');
+});
+
+const DOCUMENTED = [
+  ['modules/builder-settings/interaction-prefs.js', 'fieldCatalog', 'function'],
+  ['modules/sessions/pulse.js', 'recordPulse', 'function'],
+  ['modules/economy/cost-classify.js', 'OWNERLESS_CATEGORIES', 'object'],
+  ['modules/economy/cost-classify.js', 'SOFT_CAP_FRACTION', 'number'],
+  ['modules/provisioning/onboard-plan.js', 'CONTROL_PLANE_SHAPES', 'object'],
+];
+
+for (const [file, name, type] of DOCUMENTED) {
+  test(`${file} keeps exporting ${name}: its module CLAUDE.md names it as the module's API`, () => {
+    const doc = read(path.join(path.dirname(file), 'CLAUDE.md'));
+    assert.ok(doc.includes(name), `${name} is still documented in ${path.dirname(file)}/CLAUDE.md`);
+    const mod = require(path.join(ROOT, file));
+    assert.ok(name in mod, `${name} is exported from ${file}`);
+    assert.equal(typeof mod[name], type);
+  });
+}

package/tests/nav_permission_atoms.mjs

@@ -93,7 +93,7 @@ test('the hall-preview fixture carries every atom /me resolves', () => {
 // says a held core version was tried and rolled back; task 1004731: the one-time
 // "Upgraded to core X" notice after a move; task 1004826: Standing is Accomplishments;
 // task 1004846: the new logo (its bump landed late, in task 1004852).
-const SHELL_SHA = '670b2f71085c13b6';
+const SHELL_SHA = 'cea38eeab6b234cc';
 
 test('shell.js has not changed without its cache-bust being bumped', () => {
   const actual = crypto.createHash('sha256').update(SHELL).digest('hex').slice(0, 16);

package/tests/npm_release_where.mjs

@@ -18,7 +18,7 @@ import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
-import { npmTarball, npmPackument, fakeHttpsGet } from './helpers.mjs';
+import { npmTarball, npmPackument, fakeHttpsGet, realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -193,6 +193,7 @@ function bootWidget(answer, { shown = null } = {}) {
   const listeners = {};
   const asked = [];
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     OTBTaskShown: shown,
     BongosClient: { createClient: () => ({ request: async (m, url) => { asked.push(url); return answer(url); } }) },
   };

package/tests/page_notes_panel.mjs

@@ -13,6 +13,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -59,7 +60,7 @@ function boot({ session = {}, search = '' } = {}) {
   };
   const mk = (obj) => ({ getItem: (k) => (k in obj ? obj[k] : null), setItem: (k, v) => { obj[k] = String(v); }, removeItem: (k) => { delete obj[k]; } });
   const opened = [];
-  const window = { localStorage: mk({}), sessionStorage: mk(session), matchMedia: () => ({ matches: false }), location: { search } };
+  const window = { OTB: realOTB(), localStorage: mk({}), sessionStorage: mk(session), matchMedia: () => ({ matches: false }), location: { search } };
   // "Loading" page-notes.js: record the tag, then define the API it would define.
   head.onAppend = (tag) => {
     loaded.push(tag.src);
@@ -115,7 +116,7 @@ test('a ?note= link opens that doc on arrival, in any mode', async () => {
 
 // ---------- the reader ----------
 function reader() {
-  const window = { location: { pathname: '/studio' } };
+  const window = { OTB: realOTB(), location: { pathname: '/studio' } };
   const document = { body: { dataset: { page: 'studio', pageTitle: 'Studio' } }, title: 'Studio — hall' };
   const sandbox = { window, document };
   vm.createContext(sandbox);
@@ -206,7 +207,7 @@ function dockedPanel({ reviewing = null, opened = false } = {}) {
     experiences: () => [{ id: 'ideating', label: 'Ideator experience', short: 'Ideating' }, { id: 'building', label: 'Building experience', short: 'Building' }],
     iconHtml: () => '<svg></svg>',
   };
-  const window = { location: { pathname: '/studio' }, OTBCraftMode: craft };
+  const window = { OTB: realOTB(), location: { pathname: '/studio' }, OTBCraftMode: craft };
   const sandbox = { window, document, fetch, setTimeout, clearTimeout, Promise };
   vm.createContext(sandbox);
   vm.runInContext(NOTES, sandbox, { filename: 'page-notes.js' });

package/tests/paintbrush.mjs

@@ -17,6 +17,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -157,7 +158,7 @@ function boot({ round = null, draft = null, claim = { status: 200, body: { ok: t
     return respond(404, {});
   };
   const winListeners = {};
-  const window = { location: { pathname: '/roadmap' }, addEventListener: (t, fn) => { (winListeners[t] ||= []).push(fn); }, removeEventListener: (t, fn) => { winListeners[t] = (winListeners[t] || []).filter((f) => f !== fn); } };
+  const window = { OTB: realOTB(), location: { pathname: '/roadmap' }, addEventListener: (t, fn) => { (winListeners[t] ||= []).push(fn); }, removeEventListener: (t, fn) => { winListeners[t] = (winListeners[t] || []).filter((f) => f !== fn); } };
   const sandbox = { window, document, fetch, Promise, setTimeout, clearTimeout, JSON, Math, String, Array, Object };
   window.window = window;
   vm.createContext(sandbox);

package/tests/profile_connections_ui.mjs

@@ -58,6 +58,7 @@ import vm from 'node:vm';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
+import { realOTB } from './helpers.mjs';
 // The REAL predicates, not a copy. accountFloor() below used to spell these
 // itself, which made it a hand-maintained mirror of account-visibility.js —
 // and it drifted the moment ADR 0213 made consent two columns. Imported, the
@@ -498,7 +499,7 @@ function boot({ transport, hub = HUB } = {}) {
     window: {
       OTBAsk: require('../modules/hall-ui/public/hall-ask.js'),
       BongosClient: { createClient: () => api },
-      OTB: { $, escapeHtml, fmtDate: (d) => String(d).slice(0, 10), toast: (m) => toasts.push(m), hubOrigin: () => hub },
+      OTB: { ...realOTB(), $, escapeHtml, fmtDate: (d) => String(d).slice(0, 10), toast: (m) => toasts.push(m), hubOrigin: () => hub },
       OTBKit: {
         makePager: (prefix, key) => ({ prefix, key, page: 1, perPage: 25 }),
         makeLedger: ({ mount, rowHtml, emptyMsg }) => ({

package/tests/profile_role_headline.mjs

@@ -20,7 +20,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
-import { makeRunner } from './helpers.mjs';
+import { makeRunner, realOTB } from './helpers.mjs';
 
 process.env.NODE_ENV = 'test';
 const require = createRequire(import.meta.url);
@@ -129,7 +129,7 @@ async function boot(profileData) {
     // The real kit draws the surface bars; the section rail needs a real DOM and
     // is not what this suite is about, so it is left out (profile.js skips it).
     OTBKit: { ...OTBKit, makeSectionRail: undefined },
-    OTB: {
+    OTB: { ...realOTB(),
       $, escapeHtml,
       fmtNum: (n) => Number(n || 0).toLocaleString('en-US'),
       fmtDate: (d) => String(d).slice(0, 10),

package/tests/profile_role_tabs.mjs

@@ -22,7 +22,7 @@ import os from 'node:os';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
-import { makeRunner, bootProfilePage, settle } from './helpers.mjs';
+import { makeRunner, bootProfilePage, settle, realOTB } from './helpers.mjs';
 
 process.env.NODE_ENV = 'test';
 const require = createRequire(import.meta.url);
@@ -95,7 +95,7 @@ await test('the route: signed in only, a bad id refused, paged, and it asks for
 // ---- 2. the ideator's trail -------------------------------------------------
 
 function loadCrafts() {
-  const sandbox = { window: {}, console };
+  const sandbox = { window: { OTB: realOTB() }, console };
   sandbox.globalThis = sandbox;
   vm.createContext(sandbox);
   for (const f of ['idea-objects.js', 'profile-crafts.js']) {

package/tests/projects_hub_repo_private.mjs

@@ -17,6 +17,7 @@
 import { strict as assert } from 'node:assert';
 import { readFileSync } from 'node:fs';
 import vm from 'node:vm';
+import { realOTB } from './helpers.mjs';
 
 const HUB = readFileSync(new URL('../modules/public-landing/public/projects.html', import.meta.url), 'utf8').replace(/\r\n/g, '\n');
 
@@ -30,6 +31,8 @@ async function ta(name, fn) {
 function grab(head) {
   const at = HUB.indexOf(`\n  ${head}`);
   assert.ok(at >= 0, `${head} must exist`);
+  const line = HUB.slice(at, HUB.indexOf('\n', at + 1));
+  if (/\}\s*$/.test(line)) return line; // a one-line declaration (esc, task 1004876)
   const end = HUB.indexOf('\n  }', at + 1);
   const close = HUB.slice(end, end + 5) === '\n  };' ? end + 5 : end + 4;
   return HUB.slice(at, close);
@@ -50,6 +53,7 @@ function world({ reply = RECEIPT } = {}) {
     API: '/api/bongos', manageId: '18', manageInst: null, manageRepo: null,
     mRepoPrivSeen: false, mRepoPrivState: '',
     $: (id) => els[id],
+    window: { OTB: realOTB() }, // the page loads dom-utils.js first (task 1004876)
     document: { querySelector: () => null },
     jsonOrEmpty: (res) => res.json(),
     apiError: (data) => (data && data.error) || {},

package/tests/terms_acceptance.mjs

@@ -400,6 +400,7 @@ require.cache[moduleApiPath] = {
     resolveEnv: () => null,
     userAgent: () => 'cloud-bongos-tests',
     LIVE_RANK_LADDER: ['xenos', 'thetes', 'metic', 'archon'],
+    escapeHtml: require('../src/html-escape.js').escapeHtml, // the doorway's one escaper (task 1004876)
   },
 };
 

package/tests/welcome_boot_browser.mjs

@@ -33,7 +33,7 @@ const INDEX = fs.readFileSync(path.join(HALL, 'index.html'), 'utf8')
   .replace(/<script\b[^>]*>[\s\S]*?<\/script>/g, '')
   .replace(/\{\{[^}]*\}\}/g, '');
 const STUB = '<script>window.__BRANDING__ = { identity: { worldName: "Harbor" } }; window.BongosClient = { createClient: () => ({ request: async () => ({ ok: false, status: 404, data: null }) }) };</script>';
-const SCRIPTS = ['shell-trail.js', 'craft-mode.js', 'welcome-boot.js', 'shell.js']
+const SCRIPTS = ['dom-utils.js', 'shell-trail.js', 'craft-mode.js', 'welcome-boot.js', 'shell.js'] // dom-utils first, as on the real page (task 1004876)
   .map((f) => `<script src="/builders/${f}"></script>`).join('');
 const PAGE = INDEX.replace('</body>', STUB + SCRIPTS + '</body>');