@bongos/core 1.24.34 → 1.24.36

package/tests/hall_reading_room.mjs

@@ -0,0 +1,426 @@
+// tests/hall_reading_room.mjs — ONE reading room (task 1005046, owner decision
+// 2026-11-03, idea 1001311).
+//
+// Four Docs pages explained the same three topics — the task lifecycle, the rank
+// ladder, and credits and karma — so their copies drifted. Ranks, Economy
+// (/drachmae) and Diagrams became chapters of the Primer, each with its diagram
+// beside it. This file holds what makes that true and keeps it true:
+//
+//   * EVERY OLD URL LANDS ON ITS CHAPTER. /ranks, /drachmae and /diagrams 302 to
+//     the Primer chapter that replaced each — run against the real middleware,
+//     on both host shapes — and the diagram IMAGES under /builders/diagrams/*
+//     still serve (behind sign-in) rather than being swallowed by the redirect.
+//   * THE CHAPTERS EXIST, AND EACH CARRIES ITS DIAGRAM. Every id primer.js
+//     inlines a diagram at, every redirect target and every palette jump is a
+//     real h2/h3 slug of docs/onboarding/primer.md, computed by the SAME slugify
+//     the page runs — so retitling a chapter fails here, not silently in a
+//     browser (the credits diagram was lost that way once).
+//   * THE ECONOMY PAGE'S LIVE SECTIONS MOVED WHOLE. The treasury and the bounty
+//     rate card (primer-live.js, from drachmae.js, tasks 1003446 and 2174) are
+//     RUN in a vm against the checked-in fixtures: a Loading… line first, the
+//     real numbers after, and NOTHING — not an empty panel — when a feed fails.
+//   * THE SHARED READER the economy doc leaned on (h4, linked headings, nested
+//     emphasis) stays pinned: drachmae-and-karma.md is still the full reference.
+//
+// Moved here from tests/hall_reference_world.mjs, whose reference-room rules
+// (room--reference, the h3 outline, the heading anchors) went with the page.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import http from 'node:http';
+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)), '..');
+const HALL = path.join(ROOT, 'modules', 'hall-ui', 'public');
+const read = (f) => fs.readFileSync(path.join(HALL, f), 'utf8');
+
+const roomCss = read('room.css');
+const primerHtml = read('primer.html');
+const primerJs = read('primer.js');
+const liveJs = read('primer-live.js');
+const PRIMER_MD = fs.readFileSync(path.join(ROOT, 'docs', 'onboarding', 'primer.md'), 'utf8');
+
+const decomment = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '');
+const rule = (css, selector) => {
+  const esc = selector.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const m = decomment(css).match(new RegExp(`(^|[},])\\s*${esc}\\s*\\{([^}]*)\\}`, 'm'));
+  return m ? m[2] : null;
+};
+
+function loadReader() {
+  const sandbox = { window: { OTB: realOTB() }, location: { hostname: 'builders.example.com', href: 'https://builders.example.com/primer' } };
+  vm.createContext(sandbox);
+  vm.runInContext(read('md-reader.js'), sandbox, { filename: 'md-reader.js' });
+  return sandbox.window.OTBMdReader;
+}
+
+// The primer's headings exactly as the page renders them: parsed by the shared
+// reader, ids from its slugify.
+function primerHeadings() {
+  return loadReader().parseMarkdown(PRIMER_MD, (h) => h).headings;
+}
+const h2Ids = () => primerHeadings().filter((h) => h.level === 2).map((h) => h.id);
+
+// ---- 1. every old URL lands on its chapter ---------------------------------
+
+// The real middleware, mounted on a bare app. Nothing here needs a database:
+// the redirect runs before any gate, and the gate it hands an image to only has
+// to redirect an anonymous request into sign-in.
+async function withHall(fn) {
+  const express = require('express');
+  const { mountInternalSurfaces } = require('../src/bongos/serve-internal.js');
+  const app = express();
+  mountInternalSurfaces(app);
+  const server = app.listen(0, '127.0.0.1');
+  await new Promise((r) => server.once('listening', r));
+  const { port } = server.address();
+  const get = (p, host) => new Promise((resolve, reject) => {
+    http.get({ host: '127.0.0.1', port, path: p, headers: { host } }, (res) => {
+      res.resume();
+      res.on('end', () => resolve({ status: res.statusCode, location: res.headers.location || '' }));
+    }).on('error', reject);
+  });
+  try { await fn(get); } finally { server.close(); }
+}
+
+const CHAPTER_OF = {
+  ranks: 'the-rank-ladder',
+  drachmae: 'credits-and-karma',
+  diagrams: 'the-claim-ship-lifecycle',
+};
+
+test('RUN: /ranks, /drachmae and /diagrams each 302 to the Primer chapter that replaced them', async () => {
+  await withHall(async (get) => {
+    for (const [page, chapter] of Object.entries(CHAPTER_OF)) {
+      for (const form of [`/${page}`, `/${page}/`, `/${page}.html`]) {
+        const r = await get(form, 'builders.127.0.0.1');
+        assert.equal(r.status, 302, `${form} is a temporary redirect, so a later re-point is never cached past`);
+        assert.equal(r.location, `/primer#${chapter}`, `${form} lands on #${chapter}`);
+      }
+    }
+    // A query string rides along; the chapter is the fragment after it.
+    const q = await get('/drachmae?from=mail', 'builders.127.0.0.1');
+    assert.equal(q.location, '/primer?from=mail#credits-and-karma');
+  });
+});
+
+test('RUN: the diagram images are NOT swallowed by the redirect, and stay behind sign-in', async () => {
+  await withHall(async (get) => {
+    const img = await get('/diagrams/01-task-lifecycle.png', 'builders.127.0.0.1');
+    assert.equal(img.status, 302);
+    assert.match(img.location, /\/auth\/web\/start\?return=/, 'an anonymous image request goes to sign-in, not to the Primer');
+    const primer = await get('/primer', 'builders.127.0.0.1');
+    assert.match(primer.location, /\/auth\/web\/start\?return=/, 'and the Primer itself keeps its sign-in gate');
+  });
+});
+
+test('every redirect target is a real chapter of the Primer', () => {
+  const ids = h2Ids();
+  for (const chapter of Object.values(CHAPTER_OF)) assert.ok(ids.includes(chapter), `primer.md has an h2 slugged ${chapter}`);
+  const src = fs.readFileSync(path.join(ROOT, 'src', 'bongos', 'serve-internal.js'), 'utf8');
+  const map = src.slice(src.indexOf('const RETIRED_DOC_CHAPTER'), src.indexOf('const RETIRED_DOC_PAGE_RE'));
+  for (const [page, chapter] of Object.entries(CHAPTER_OF)) {
+    assert.match(map, new RegExp(`${page}: '${chapter}'`), `serve-internal.js sends /${page} to #${chapter}`);
+  }
+});
+
+// ---- 2. the chapters, each with its diagram --------------------------------
+
+const diagramTable = () => [...primerJs.matchAll(/\{ id: '([a-z0-9-]+)',\s*src: '\/builders\/diagrams\/([\w.-]+)'/g)]
+  .map((m) => ({ id: m[1], file: m[2] }));
+
+test('all five diagrams are inlined, each at a chapter that exists', () => {
+  const table = diagramTable();
+  assert.deepEqual(table.map((d) => d.file.replace(/\.png$/, '')).sort(),
+    fs.readdirSync(path.join(ROOT, 'docs', 'onboarding', 'diagrams')).filter((f) => f.endsWith('.mmd')).map((f) => f.replace(/\.mmd$/, '')).sort(),
+    'one figure per diagram source, none left without a chapter');
+  const ids = h2Ids();
+  for (const d of table) assert.ok(ids.includes(d.id), `${d.file} is inlined at #${d.id}, which primer.md must have`);
+  assert.equal(new Set(table.map((d) => d.id)).size, table.length, 'and no chapter carries two');
+});
+
+test('the lifecycle, the rank ladder and credits and karma are each explained ONCE', () => {
+  const ids = h2Ids();
+  for (const chapter of ['the-claim-ship-lifecycle', 'the-rank-ladder', 'credits-and-karma']) {
+    assert.equal(ids.filter((id) => id === chapter).length, 1, `one #${chapter} chapter`);
+  }
+  // The ladder chapter carries what the Ranks page said: every live rank, and
+  // how each promotion happens.
+  const ladder = PRIMER_MD.slice(PRIMER_MD.indexOf('## The rank ladder'), PRIMER_MD.indexOf('## Credits and karma'));
+  for (const rank of ['Xenos', 'Thetes', 'Metic', 'Archon']) assert.match(ladder, new RegExp(`\\*\\*${rank}\\*\\*`));
+  assert.match(ladder, /### How you advance/);
+  assert.match(ladder, /\/builders#accomplishments-progress/, 'and it points the reader at their own standing');
+});
+
+test('the two stale primer lines are gone', () => {
+  assert.doesNotMatch(PRIMER_MD, /touches the game/, 'the core has no game');
+  assert.doesNotMatch(PRIMER_MD, /Entry to the project is \*\*approval-gated\*\*/);
+  assert.match(PRIMER_MD, /\*\*depends on the project\*\*/, 'entry depends on the project');
+});
+
+test('the primer keeps a hall address in the hall, and sends repo paths to GitHub', () => {
+  const sandbox = { window: { OTB: realOTB() }, document: { readyState: 'complete', querySelector: () => null } };
+  vm.createContext(sandbox);
+  vm.runInContext(read('md-reader.js'), sandbox, { filename: 'md-reader.js' });
+  // Lift the resolver out of primer.js without booting the page.
+  const src = primerJs.slice(primerJs.indexOf('  const resolveLinkHref = (() => {'), primerJs.indexOf('  function toast('));
+  const fn = vm.runInContext(`(() => { const MD = window.OTBMdReader; const PRIMER_DIR = 'docs/onboarding/'; let repoBlobBase = 'https://gh/blob/main'; let repoTreeBase = 'https://gh/tree/main';\n${src}\nreturn resolveLinkHref; })()`, sandbox);
+  assert.equal(fn('/builders#accomplishments-progress'), '/builders#accomplishments-progress');
+  assert.equal(fn('drachmae-and-karma.md'), 'https://gh/blob/main/docs/onboarding/drachmae-and-karma.md',
+    'the full reference is a repo doc now that its hall page is a chapter');
+  assert.equal(fn('../adr/'), 'https://gh/tree/main/docs/adr');
+  assert.equal(fn('/buildersx/'), 'https://gh/tree/main/buildersx', 'only a real /builders address is kept');
+});
+
+// Lift insertLiveSections out of primer.js (with the two consts it reads) and run
+// it against a fake article, a fake OTBPrimerLive and a controllable observer.
+function liftInsertLive({ hash = '', withObserver = true }) {
+  const src = primerJs.slice(primerJs.indexOf('  const LIVE_HASHES'), primerJs.indexOf('  // A deep link — /primer#the-rank-ladder'));
+  const fills = [];
+  const observers = [];
+  const window = {
+    location: { hash },
+    OTBPrimerLive: {
+      placeholder: (kind) => ({ kind }),
+      fillTreasury: async (s) => { fills.push(s.kind); return true; },
+      fillBounty: async (s) => { fills.push(s.kind); return true; },
+    },
+  };
+  if (withObserver) {
+    window.IntersectionObserver = class {
+      constructor(cb) { this.cb = cb; this.targets = []; observers.push(this); }
+      observe(t) { this.targets.push(t); }
+      disconnect() { this.gone = true; }
+    };
+  }
+  const next = { tagName: 'H2' };
+  const h = { tagName: 'H2', nextElementSibling: { tagName: 'P', nextElementSibling: next } };
+  const placed = [];
+  const article = {
+    querySelector: (sel) => (sel === 'h2[id="credits-and-karma"]' ? h : null),
+    insertBefore: (el, ref) => placed.push([el.kind, ref === next]),
+    appendChild: (el) => placed.push([el.kind, false]),
+  };
+  const ctx = { window, Promise };
+  vm.createContext(ctx);
+  const fn = vm.runInContext(`(() => { const LIVE_CHAPTER_ID = 'credits-and-karma';\n${src}\nreturn insertLiveSections; })()`, ctx);
+  return { run: () => fn(article), fills, observers, placed };
+}
+
+test('RUN: the live reads wait until the reader comes near, so an ordinary Primer visit costs nothing', async () => {
+  const t = liftInsertLive({ hash: '#the-rank-ladder' });
+  await t.run();
+  assert.deepEqual(t.placed, [['treasury', true], ['bounty', true]], 'both placed at the end of the credits chapter, ahead of the next one');
+  assert.deepEqual(t.fills, [], 'no fetch on load');
+  assert.equal(t.observers.length, 1);
+  t.observers[0].cb([{ isIntersecting: false }]);
+  assert.deepEqual(t.fills, [], 'nor while they are still far away');
+  t.observers[0].cb([{ isIntersecting: true }]);
+  t.observers[0].cb([{ isIntersecting: true }]);
+  await Promise.resolve();
+  assert.deepEqual(t.fills, ['treasury', 'bounty'], 'one read each, once, when the reader approaches');
+  assert.equal(t.observers[0].gone, true, 'and the watch is dropped');
+});
+
+test('RUN: an old /drachmae link (or a section address) fills at once, so the landing is on the final layout', async () => {
+  for (const hash of ['#credits-and-karma', '#the-treasury', '#security-bounty-rates']) {
+    const t = liftInsertLive({ hash });
+    await t.run();
+    assert.deepEqual(t.fills, ['treasury', 'bounty'], `${hash} reads both before landing`);
+    assert.equal(t.observers.length, 0);
+  }
+  const old = liftInsertLive({ withObserver: false });
+  await old.run();
+  assert.deepEqual(old.fills, ['treasury', 'bounty'], 'a browser with no observer still gets the sections');
+});
+
+test('a deep link lands after the article, its live sections and the fonts', () => {
+  const boot = primerJs.slice(primerJs.indexOf('async function boot()'));
+  assert.match(boot, /const live = insertLiveSections\(article\);/);
+  assert.match(boot, /live\.then\(\(\) => \(document\.fonts \? document\.fonts\.ready : null\)\)\.then\(landOnHash\);/);
+});
+
+test('the states file shoots a redirected deep link, not just the top of the page', () => {
+  const states = JSON.parse(read('primer.states.json'));
+  assert.match(states.states.jump.url, /#credits-and-karma$/);
+});
+
+// ---- 3. the live sections, RUN ---------------------------------------------
+
+const costSummaryFixture = JSON.parse(
+  fs.readFileSync(path.join(ROOT, 'modules', 'ui-design', 'kit', 'fixtures', 'cost-summary.json'), 'utf8'),
+);
+const bountyFixture = JSON.parse(
+  fs.readFileSync(path.join(ROOT, 'scripts', 'hall-preview', 'fixtures', 'public__bounty-table.json'), 'utf8'),
+);
+
+// Just enough of an element for primer-live.js: it only ever writes a section's
+// innerHTML, its data-live and aria-busy, and removes it.
+function fakeSection() {
+  return {
+    className: '', dataset: {}, attrs: {}, innerHTML: '', removed: false,
+    setAttribute(k, v) { this.attrs[k] = String(v); },
+    removeAttribute(k) { delete this.attrs[k]; },
+    remove() { this.removed = true; },
+  };
+}
+
+async function loadLive({ responses, branding = { currency: { label: 'drachmae' } }, kit = true }) {
+  const warnings = [];
+  const sandbox = {
+    window: { OTB: realOTB(), __BRANDING__: branding },
+    document: { createElement: () => fakeSection() },
+    console: { warn: (...a) => warnings.push(a.join(' ')) },
+    fetch: async (url) => {
+      const r = responses[url];
+      if (r instanceof Error) throw r;
+      if (!r) return { ok: false, status: 404, json: async () => ({}) };
+      return { ok: true, status: 200, json: async () => r };
+    },
+  };
+  if (kit) {
+    const kitPath = path.join(HALL, 'hall-kit.js');
+    sandbox.window.OTBKit = await import(`file://${kitPath.replace(/\\/g, '/')}`).then((m) => m.default);
+  }
+  vm.createContext(sandbox);
+  vm.runInContext(liveJs, sandbox, { filename: 'primer-live.js' });
+  return { live: sandbox.window.OTBPrimerLive, warnings };
+}
+
+const TREASURY = '/api/bongos/public/cost-summary';
+const BOUNTY = '/api/bongos/public/bounty-table';
+
+test('RUN: a section says Loading… the moment it is placed, under the heading a deep link needs', async () => {
+  const { live } = await loadLive({ responses: {} });
+  for (const [kind, id] of [['treasury', 'the-treasury'], ['bounty', 'security-bounty-rates']]) {
+    const s = live.placeholder(kind);
+    assert.match(s.innerHTML, new RegExp(`^<h3 id="${id}">`), `${kind} carries its address from the start`);
+    assert.match(s.innerHTML, /<p class="hall-loading" role="status">Loading…<\/p>/);
+    assert.equal(s.attrs['aria-busy'], 'true');
+  }
+});
+
+test('RUN: the treasury fills from the payload, and its line ends on the total the prose states', async () => {
+  const { live } = await loadLive({ responses: { [TREASURY]: costSummaryFixture } });
+  const s = live.placeholder('treasury');
+  assert.equal(await live.fillTreasury(s), true);
+  assert.equal(s.removed, false);
+  assert.equal(s.attrs['aria-busy'], undefined, 'no longer busy');
+  assert.doesNotMatch(s.innerHTML, /Loading…/);
+  assert.match(s.innerHTML, /^<h3 id="the-treasury">The treasury, so far<\/h3>/);
+  const usd = `$${Number(costSummaryFixture.total_usd).toLocaleString(undefined, { maximumFractionDigits: 0 })}`;
+  assert.ok(s.innerHTML.includes(`<strong>${usd}</strong>`), 'the spend total is stated');
+  assert.match(s.innerHTML, /id="treasury-spend"/);
+  assert.match(s.innerHTML, /id="treasury-earned"/);
+  assert.match(s.innerHTML, /Drachmae awarded, cumulative/, 'the currency word is the branding pack\'s');
+  assert.doesNotMatch(s.innerHTML, /NaN|Infinity/, 'a NaN in a path renders as an invisible chart with no error anywhere');
+  assert.doesNotMatch(s.innerHTML, /tabindex="0"/, 'no focus stop: nothing here wires a readout');
+  assert.doesNotMatch(s.innerHTML, /&amp;amp;|&amp;#/, 'nothing is escaped twice');
+});
+
+test('RUN: a treasury that cannot be read, or holds nothing yet, leaves NO section behind', async () => {
+  for (const responses of [{}, { [TREASURY]: new Error('down') }, { [TREASURY]: { daily: [], daily_credits: [] } }]) {
+    const { live } = await loadLive({ responses });
+    const s = live.placeholder('treasury');
+    assert.equal(await live.fillTreasury(s), false);
+    assert.equal(s.removed, true, 'the Loading… line goes with it — never an empty panel');
+  }
+  const noKit = await loadLive({ responses: { [TREASURY]: costSummaryFixture }, kit: false });
+  const s = noKit.live.placeholder('treasury');
+  assert.equal(await noKit.live.fillTreasury(s), false, 'without the chart kit there is nothing honest to draw');
+  assert.equal(s.removed, true);
+  assert.match(noKit.warnings.join('\n'), /OTBKit missing/);
+});
+
+test('RUN: the bounty rate card renders the live table, tuned tiers marked', async () => {
+  const tuned = { ...bountyFixture, table: bountyFixture.table.map((r, i) => (i === 0 ? { ...r, overridden: true } : r)) };
+  const { live } = await loadLive({ responses: { [BOUNTY]: tuned }, branding: {} });
+  const s = live.placeholder('bounty');
+  assert.equal(await live.fillBounty(s), true);
+  assert.match(s.innerHTML, /^<h3 id="security-bounty-rates">Security bounty rates<\/h3>/);
+  assert.equal((s.innerHTML.match(/<tr><td><strong>/g) || []).length, bountyFixture.table.length, 'one row per severity');
+  assert.match(s.innerHTML, /<em>\(tuned\)<\/em>/);
+  assert.match(s.innerHTML, /<th>Credits<\/th>/, 'the neutral currency word when the pack names none');
+});
+
+test('RUN: a bounty feed that fails leaves no section', async () => {
+  for (const responses of [{}, { [BOUNTY]: { table: [] } }]) {
+    const { live } = await loadLive({ responses });
+    const s = live.placeholder('bounty');
+    assert.equal(await live.fillBounty(s), false);
+    assert.equal(s.removed, true);
+  }
+});
+
+test('the live sections read endpoints that already existed, and draw only through the kit', () => {
+  assert.match(liveJs, /TREASURY_URL = '\/api\/bongos\/public\/cost-summary'/);
+  assert.match(liveJs, /BOUNTY_URL = '\/api\/bongos\/public\/bounty-table'/);
+  for (const fn of ['cumulateByDay', 'timeStepSeriesHtml', 'plotSvgHtml', 'plotValueLabelHtml', 'barSeriesHtml']) {
+    assert.match(liveJs, new RegExp(`kit\\.${fn}\\(`), `the treasury draws through ${fn}`);
+  }
+  assert.doesNotMatch(liveJs, /<(?:path|polyline|rect)\b[^>]*\b(?:d|points)="\$\{/, 'no hand-built SVG geometry');
+});
+
+test('the page loads the kit, then the live module, then the page script', () => {
+  const loaded = [...primerHtml.matchAll(/<script[^>]+src="([^"?]+)/g)].map((m) => m[1].split('/').pop());
+  const at = (f) => loaded.indexOf(f);
+  assert.ok(at('hall-kit.js') > -1 && at('primer-live.js') > -1 && at('primer.js') > -1);
+  assert.ok(at('hall-kit.js') < at('primer-live.js') && at('primer-live.js') < at('primer.js'));
+  // The figure chrome is shared (style.css), so the Primer needs no profile sheet.
+  assert.match(primerHtml, /style\.css/);
+  assert.doesNotMatch(primerHtml, /profile\.css/);
+});
+
+// ---- 4. the shared reader, actually run -------------------------------------
+
+test('the shared parser reaches h4 — the reference doc\'s earning sources are ####', () => {
+  const MD = loadReader();
+  const { html, headings } = MD.parseMarkdown('#### 4. Achievements\n\nUnlocking one pays its bonus.\n', (h) => h);
+  assert.equal(headings.length, 1);
+  assert.equal(headings[0].level, 4);
+  assert.match(html, /<h4 id="4-achievements">4\. Achievements<\/h4>/);
+  assert.doesNotMatch(html, /####/);
+});
+
+test('a paragraph breaks before an h4 the way it breaks before an h3', () => {
+  const MD = loadReader();
+  const { html } = MD.parseMarkdown('a line\n#### A head\n', (h) => h);
+  assert.match(html, /<p>a line<\/p>\s*<h4/);
+});
+
+test('a heading that carries a link slugs by its text, so the copied address stays readable', () => {
+  const MD = loadReader();
+  const withLink = '2. Per-task credits, adjusted by *kind* ([ADR 0023](../adr/0023-kind-multipliers-and-idea-bonus.md))';
+  assert.equal(MD.slugify(withLink), MD.slugify('2. Per-task credits, adjusted by *kind* (ADR 0023)'));
+  assert.doesNotMatch(MD.slugify(withLink), /adr0023|md$/, 'the target path is not part of the address');
+});
+
+test('emphasis inside a bold run renders — the API list-price line showed its asterisks', () => {
+  const MD = loadReader();
+  const { html } = MD.parseMarkdown('- **It is the API *list* price, deliberately** and not the rest\n', (h) => h);
+  assert.match(html, /<strong>It is the API <em>list<\/em> price, deliberately<\/strong> and not the rest/);
+  const two = MD.parseMarkdown('**a** and **b**\n', (h) => h).html;
+  assert.match(two, /<strong>a<\/strong> and <strong>b<\/strong>/, 'and two bold runs on one line stay two');
+});
+
+test('the room gives the fourth level a rule, the measure and the anchor offset', () => {
+  const h4 = rule(roomCss, '.primer-article h4');
+  assert.ok(h4, 'room.css styles h4 (the treasury\'s "Where it went" is one)');
+  assert.match(h4, /scroll-margin-top/, 'a deep link to an h4 clears the top bar');
+  const measured = decomment(roomCss).match(/\.primer-article\s*>\s*p,[\s\S]*?\{([^}]*)\}/);
+  assert.ok(measured, 'the measured-children list exists');
+  assert.match(measured[0], /\.primer-article\s*>\s*h4/, 'and the h4 is measured with the prose');
+});
+
+test('the reference rules left with the reference page', () => {
+  assert.doesNotMatch(decomment(roomCss), /room--reference/, 'no rule keyed on a body class no page wears');
+  for (const f of fs.readdirSync(HALL).filter((n) => n.endsWith('.html'))) {
+    assert.doesNotMatch(read(f), /room--reference/, `${f} wears no reference modifier`);
+  }
+});

package/tests/hall_reading_world.mjs

@@ -68,16 +68,13 @@ const read = (f) => fs.readFileSync(path.join(HALL, f), 'utf8');
 const styleCss = read('style.css');
 const roomCss = read('room.css');
 const primerCss = read('primer.css');
-const diagramsCss = read('diagrams.css');
 const roadmapCss = read('roadmap.css');
 const viewerCss = read('diagram-viewer.css');
 const primerJs = read('primer.js');
 const viewerJs = read('diagram-viewer.js');
 const mdReaderJs = read('md-reader.js');
 const primerHtml = read('primer.html');
-const diagramsHtml = read('diagrams.html');
 const roadmapHtml = read('roadmap.html');
-const ranksHtml = read('ranks.html');
 
 const decomment = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '');
 // The body of the first rule matching `selector {`, comments stripped. Naive on
@@ -94,7 +91,6 @@ const rule = (css, selector) => {
 const RESKINNED = [
   ['room.css', roomCss],
   ['primer.css', primerCss],
-  ['diagrams.css', diagramsCss],
   ['roadmap.css', roadmapCss],
   ['diagram-viewer.css', viewerCss],
 ];
@@ -143,14 +139,18 @@ test('no re-skinned reading-room sheet spends a compat alias', () => {
     'the aliases exist for pages nobody has re-skinned; spending one here quietly opts the sheet back out of the world');
 });
 
-test('the ranks page section of style.css spends the real names too', () => {
-  const card = rule(styleCss, '.rank-card');
-  assert.ok(card, '.rank-card has a rule');
-  for (const alias of ALIASES) {
-    assert.doesNotMatch(card, new RegExp(`var\\(\\s*${alias}\\s*[,)]`), `.rank-card no longer spends ${alias}`);
+// task 1005046: the Ranks page folded into the Primer; its ladder cards went with
+// it and "Where you stand" (Accomplishments) kept the standing rules, which hold
+// the same line.
+test('the "Where you stand" section of style.css spends the real names too', () => {
+  for (const sel of ['.ranks-standing', '.ranks-standing__blurb', '.ranks-standing__next', '.ranks-rise__body']) {
+    const body = rule(styleCss, sel);
+    assert.ok(body, `${sel} has a rule`);
+    for (const alias of ALIASES) {
+      assert.doesNotMatch(body, new RegExp(`var\\(\\s*${alias}\\s*[,)]`), `${sel} spends no ${alias}`);
+    }
   }
-  assert.match(card, /border:\s*var\(--line\)\s+solid\s+transparent/,
-    'the edge is reserved as transparent so a modifier can draw one — collab.css\'s .btn--quiet is the precedent');
+  assert.equal(rule(styleCss, '.rank-card'), null, 'the ladder cards left with the page');
 });
 
 test('the alias guard would CATCH --surface without matching --surface-2', () => {
@@ -223,8 +223,11 @@ test('primer.html loads the reader BEFORE the page script', () => {
 });
 
 test('the primer keeps the one rewrite that is its own', () => {
-  assert.match(primerJs, /drachmae-and-karma\.md.*\/builders\/drachmae/s,
-    'the economy doc has an in-hall reader page (task 1472); a link to it must stay in the hall, not bounce to GitHub');
+  // task 1005046: the economy doc's in-hall page became a Primer chapter, so the
+  // rewrite that kept a link to it in the hall is gone; what is the primer's own
+  // now is a /builders address (run in tests/hall_reading_room.mjs).
+  assert.doesNotMatch(primerJs, /'\/builders\/drachmae'/, 'no link is sent to the retired Economy page');
+  assert.match(primerJs, /\/\^\\\/builders/, 'a hall address stays in the hall');
   assert.match(primerJs, /baseDir:\s*PRIMER_DIR/, 'and resolves its relative links against docs/onboarding/');
 });
 
@@ -237,7 +240,7 @@ test('the room styles what the shared parser emits that the old copy never did',
 
 test('primer.js still injects the diagrams — the one parser-adjacent job that is the primer\'s', () => {
   assert.match(primerJs, /function inlineDiagrams/);
-  assert.match(primerJs, /DIAGRAM_AT_HEADING/);
+  assert.match(primerJs, /DIAGRAM_AT_CHAPTER/, 'keyed by chapter id (tests/hall_reading_room.mjs checks each id exists)');
   assert.match(primerJs, /fig\.className = 'primer-figure'/,
     'the injected figure takes the class diagram-viewer.js upgrades and room.css frames');
 });
@@ -285,17 +288,19 @@ test('the fullscreen scroll lock is on the root, where the shell already locks',
   assert.match(decomment(styleCss), /html\.drawer-open/, 'and that is the convention it is matching');
 });
 
-test('the room frames BOTH figures the viewer upgrades', () => {
-  assert.match(viewerJs, /figure\.diagram img, figure\.primer-figure img/,
-    'one selector, two classes — the viewer has always treated them as one object');
-  const frame = decomment(roomCss).match(/\.primer-figure,\s*figure\.diagram\s*\{([^}]*)\}/);
-  assert.ok(frame, 'and the room frames them in one rule, so they cannot drift apart');
-  assert.match(frame[1], /var\(--glass\)/);
+test('the room frames the figure the viewer upgrades', () => {
+  // task 1005046: the diagrams index's `figure.diagram` was the second class; with
+  // that page folded into the primer, the primer's figure is the only one.
+  assert.match(viewerJs, /SELECTOR = 'figure\.primer-figure img'/, 'the viewer upgrades the primer\'s figures');
+  assert.doesNotMatch(decomment(roomCss), /figure\.diagram/, 'and the room keeps no rule for a class no page draws');
+  const frame = rule(roomCss, '.primer-figure');
+  assert.ok(frame, 'the room frames the figure');
+  assert.match(frame, /var\(--glass\)/);
   // the canvas is inserted INSIDE the figure, so exactly one of the two draws
   // the frame or the diagram lands in nested boxes
-  const inner = decomment(roomCss).match(/\.primer-figure \.dgv,\s*figure\.diagram \.dgv\s*\{([^}]*)\}/);
+  const inner = rule(roomCss, '.primer-figure .dgv');
   assert.ok(inner, 'the inserted canvas gives up its own frame');
-  assert.match(inner[1], /border:\s*0/);
+  assert.match(inner, /border:\s*0/);
 });
 
 // ---- 7b. the figure follows the theme (task 1003639) ----------------------
@@ -326,8 +331,8 @@ test('dark turns the canvas figure, in both twins, byte-identical', () => {
   assert.doesNotMatch(rule(viewerCss, '.dgv__pan svg'), /filter/, 'light keeps the render exactly as mermaid drew it');
 });
 
-test('the fallback PNG turns with it, on BOTH figures the viewer upgrades', () => {
-  const both = (pre) => `${pre} .primer-figure img, ${pre} figure.diagram img`;
+test('the fallback PNG turns with it, on the figure the viewer upgrades', () => {
+  const both = (pre) => `${pre} .primer-figure img`;
   const sw = rule(roomCss, both('html[data-theme="dark"]'));
   const media = mediaRule(roomCss, both('html:not([data-theme])'));
   assert.ok(sw && media, 'the PNG shows before the SVG arrives and whenever it cannot — a dark reader must not get a white flash');
@@ -344,7 +349,8 @@ test('the viewer drops the white ground mermaid bakes into the SVG', () => {
 
 // ---- 8. every room has exactly one h1 -------------------------------------
 
-const ROOMS = [['primer.html', primerHtml], ['diagrams.html', diagramsHtml], ['roadmap.html', roadmapHtml], ['ranks.html', ranksHtml]];
+// task 1005046: diagrams.html and ranks.html folded into the primer's chapters.
+const ROOMS = [['primer.html', primerHtml], ['roadmap.html', roadmapHtml]];
 
 // An HTML comment that mentions <h1> is prose, not markup — and these pages each
 // carry one explaining why the heading is there at all.
@@ -358,8 +364,8 @@ test('every reading room renders exactly one h1, and it is the page head\'s', ()
   }
 });
 
-test('the three DOCS rooms take the room voice; the deck takes the board\'s', () => {
-  for (const [name, html] of [['primer.html', primerHtml], ['diagrams.html', diagramsHtml], ['ranks.html', ranksHtml]]) {
+test('the DOCS room takes the room voice; the deck takes the board\'s', () => {
+  for (const [name, html] of [['primer.html', primerHtml]]) {
     assert.match(html, /class="page-head page-head--room"/, `${name} is a reading room`);
   }
   assert.match(roadmapHtml, /class="page-head page-head--board"/,
@@ -375,7 +381,7 @@ test('the document\'s own h1 is suppressed, or the article would render a second
 // ---- 9. the archetype's shape ---------------------------------------------
 
 test('the room opts in from its markup, and the archetype sheet is what carries it', () => {
-  for (const [name, html] of [['primer.html', primerHtml], ['diagrams.html', diagramsHtml]]) {
+  for (const [name, html] of [['primer.html', primerHtml]]) {
     assert.match(html, /<body class="room[^"]*"/, `${name} opts into the room`);
     assert.match(html, /href="\/builders\/room\.css"/, `${name} loads the archetype`);
   }
@@ -724,13 +730,13 @@ test('the timeline module is a pure builder, so it is testable and cannot boot i
 // reader sees, and a script writing into one is a message nobody gets.
 test('every Docs page head holds only its h1, and no script writes into it', () => {
   const pub = path.join(ROOT, 'modules/hall-ui/public');
-  for (const page of ['primer', 'ranks', 'drachmae', 'commands', 'diagrams', 'atlas', 'modules']) {
+  for (const page of ['primer', 'commands', 'atlas', 'modules']) {
     const html = dehtmlcomment(fs.readFileSync(path.join(pub, `${page}.html`), 'utf8'));
     const head = html.match(/<div class="page-head[^"]*">([\s\S]*?)<\/div>/);
     assert.ok(head, `${page}.html keeps its head for the h1`);
     assert.doesNotMatch(head[1], /page-head__eyebrow|page-head__sub/, `${page}.html's hidden head holds no eyebrow or sub-line`);
   }
-  for (const [file, id] of [['ranks.js', 'ranks-sub'], ['modules.js', 'modules-sub']]) {
+  for (const [file, id] of [['modules.js', 'modules-sub']]) {
     assert.ok(!fs.readFileSync(path.join(pub, file), 'utf8').includes(id), `${file} no longer writes into #${id}`);
   }
 });

package/tests/hall_sitemap.mjs

@@ -61,6 +61,31 @@ test('a link is read the ways the hall writes one, and an unknown one is broken'
   assert.equal(gen.classify('/builders/style.css?v=1', urls), null, 'an asset is not a page link');
 });
 
+test('the Primer links to Repo Atlas and Commands, and in the hall they open those pages (task 1005069)', () => {
+  const primer = model.pages.find((p) => p.url === '/primer');
+  for (const u of ['/atlas', '/commands']) {
+    assert.ok(primer.out.includes(u), `/primer links to ${u}`);
+    assert.ok(model.pages.find((p) => p.url === u).in.includes('/primer'), `${u} is linked from /primer`);
+  }
+  // primer.js's own rewrite, run on the primer's own links: each opens its hall page
+  const src = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/primer.js'), 'utf8');
+  const literal = /const HALL_PAGE = (\/.+\/);/.exec(src);
+  assert.ok(literal, 'primer.js declares the hall-page rewrite');
+  const HALL_PAGE = new RegExp(literal[1].slice(1, -1));
+  const md = fs.readFileSync(path.join(ROOT, gen.CONTENT['/primer']), 'utf8');
+  const hrefs = [...md.matchAll(/\]\(((?:\.\.\/)+modules\/hall-ui\/public\/[a-z0-9-]+\.html)\)/g)].map((m) => m[1]);
+  assert.ok(hrefs.length >= 2);
+  const urls = new Set(model.pages.map((p) => p.url));
+  for (const h of hrefs) {
+    const m = HALL_PAGE.exec(h);
+    assert.ok(m, `${h} is rewritten by primer.js`);
+    assert.ok(urls.has('/' + m[1]), `${h} names a real hall page`);
+  }
+  // a primer link to a page that does not exist is a broken link, not a silent miss
+  assert.deepEqual(gen.mdHallLinks('[x](../../modules/hall-ui/public/no-such-page.html)'), ['/no-such-page']);
+  assert.equal(gen.classify('/no-such-page', urls), false);
+});
+
 test('the street is Governing\'s home: no nav item, reached by clicking from the city', () => {
   const street = model.pages.find((p) => p.url === '/street');
   assert.ok(street, 'the street is a hall page');

package/tests/nav_permission_atoms.mjs

@@ -94,8 +94,9 @@ test('the hall-preview fixture carries every atom /me resolves', () => {
 // "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); task 1004938: the
 // Market Watch settings nav item and its fuel glyph; task 1005041: the Update pill replaced the
-// core-update banner; task 1005045: the Market Watch settings item left (one sidebar item).
-const SHELL_SHA = '4a4b9795cdea422c';
+// core-update banner; task 1005045: the Market Watch settings item left (one sidebar item);
+// task 1005046: Ranks, Economy and Diagrams left Docs (one reading room, the Primer).
+const SHELL_SHA = '36c64a1cf84e9db1';
 
 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/rank_tier_single_source.mjs

@@ -92,7 +92,6 @@ const EXACT_LADDER_RE = /\[\s*'xenos',\s*'thetes',\s*'metic',\s*'archon'\s*\]/;
 const STATIC_LADDER_FILES = [
   'modules/discord/discord-channels.js',
   'modules/memory/search.js',
-  'modules/hall-ui/public/ranks.js',
   'modules/hall-ui/public/profile.js',
   'modules/hall-ui/public/watch.js',
   // task 1003094: the Constitution panel and the Board Room's sitting card both