@bongos/core 1.19.1056 → 1.19.1058

package/scripts/gds/publish-manifest.js

@@ -124,6 +124,13 @@ const PUBLISH_ALLOWLIST = [
   // only because that is where their generator has always written them.
   'docs/copy-registry.json',
   'docs/copy-inventory.md',          // the human twin, generated in the same pass
+  // Tweak Mode's two page artifacts (ADR 0341 D1, task 1004316), the same kind
+  // of runtime data: modules/copy-desk/page-data.js reads both on every page
+  // status read, and neither generator can run on a deployed box (the reader
+  // opens a browser against a source tree). Without the inventory an instance
+  // answers 503 page_inventory_missing; without the readings drift reads unknown.
+  'docs/page-inventory.json',
+  'docs/page-readings.json',
   'docs/file-map.md',
   'docs/repo-map.md',
   'docs/handoff-template.md',         // the portable session-handoff format (methodology)

package/scripts/gds/ship-check.js

@@ -35,6 +35,8 @@ const STEPS = [
   { key: 'api-docs', label: 'docs/api/openapi.json + api-reference fresh', argv: ['scripts/gds/gen-api-docs.js', '--check'], fix: 'node scripts/gds/gen-api-docs.js' },
   { key: 'copy-registry', label: 'docs/copy-registry.json fresh', argv: ['scripts/gds/copy-inventory.js', '--check'], fix: 'node scripts/gds/copy-inventory.js', optional: true },
   { key: 'page-inventory', label: 'docs/page-inventory.json fresh (every page + its stable id)', argv: ['scripts/gds/page-inventory.js', '--check'], fix: 'node scripts/gds/page-inventory.js', optional: true },
+  // The page readings (task 1004315, ADR 0341 D3): files_hash only, no browser; the fix is the reader's own re-read.
+  { key: 'page-readings', label: 'docs/page-readings.json fresh (every page\'s reading matches its files)', argv: ['scripts/gds/page-reader.js', '--check'], fix: 'node scripts/gds/page-reader.js --stale', optional: true },
   { key: 'linkify', label: 'no bare #NNN task refs in committed markdown', argv: ['scripts/gds/linkify-refs.js', '--check'], fix: 'node scripts/gds/linkify-refs.js', optional: true },
   { key: 'skill-lint', label: 'SKILL.md frontmatter parses', argv: ['scripts/gds/skill-lint.js'], fix: 'fix the ✗ lines (description: >- block scalars)' },
   { key: 'render-fit', label: 'rendered text fit + sibling overlap on the pages this branch changed (advisory)', argv: ['scripts/gds/render-check.js'], fix: 'look at the shots it names; fix the element, or say in the ship notes why it is right', advisory: true, optional: true, skipWith: '--no-render', slow: true },

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.1056'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1058'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/copy_desk_page_reads.mjs

@@ -0,0 +1,194 @@
+// tests/copy_desk_page_reads.mjs — Tweak Mode's three reads, the WHOLE path
+// (task 1004316 / BV2.TW05, ADR 0341 D1, D8, D11).
+//
+// modules/copy-desk/tests/copy_page_status.mjs proves the derivation on
+// hand-shaped rows. This proves the path those rows actually travel: the real
+// lifecycle port's SQL (listPageTweakTasks, shippedTasksTouchingSince) and the
+// real reward port's creditLedger, answered by a fake pool, through the real
+// copy-desk routes and the real error envelope, reading the page artifacts from
+// disk through page-data.js. A field the SQL names and the derivation does not
+// read (or the reverse) reds here and nowhere else.
+//
+// And the degrade (ADR 0341 D1): an instance with no page inventory answers a
+// named 503 carrying the generator command, never a crash, while the tally,
+// which needs no inventory, still answers; an instance with the inventory but
+// no readings still reports status and marks drift unknown.
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { makeRunner } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+
+const F = require('../modules/copy-desk/tests/fixtures/page-tweak.cjs');
+const api = require('../src/module-api.js');
+
+// The fake pool, dispatching on the SQL each port read sends. Installed BEFORE
+// the ports are required: economy/credits.js destructures the pool at load.
+const seen = [];
+const flat = (sql) => String(sql).replace(/\s+/g, ' ').trim();
+api.pool = {
+  async query(sql, params = []) {
+    const q = flat(sql);
+    seen.push({ q, params });
+    if (/FROM tasks t LEFT JOIN task_grades g/.test(q)) {
+      assert.match(q, /WHERE t\.source = 'page-tweak'/);
+      // The fixture rows stand in for this SELECT, so every column they carry
+      // must be one the SELECT really names: a renamed alias would otherwise
+      // leave the fake answering with a field the real query never returns.
+      const select = q.slice(q.indexOf(') SELECT '), q.indexOf(' FROM tasks t LEFT JOIN'));
+      // One pass over claims for the round's artist, never a per-task subquery.
+      assert.doesNotMatch(q, /LATERAL/);
+      for (const col of Object.keys(F.TASKS[0])) {
+        assert.match(select, new RegExp(`(?:t\\.${col}\\b|AS ${col}\\b)`), `the SELECT must name ${col}`);
+      }
+      return { rows: F.TASKS };
+    }
+    if (/t\.touches && \$1::text\[\]/.test(q)) {
+      return { rows: F.STUDIO_SHIPS.filter((s) => new Date(s.shipped_at) > new Date(params[1])) };
+    }
+    if (/FROM credit_log/.test(q)) {
+      const prefix = String(params[1] || '').replace(/%$/, '').replace(/\\([\\%_])/g, '$1');
+      const rows = F.CREDIT_ROWS
+        .filter((r) => String(r.builder_id) === String(params[0]) && r.reason.startsWith(prefix))
+        .map((r) => ({ ...r }));
+      return { rows: rows.map((r, _, all) => ({ ...r, total_count: all.length })) };
+    }
+    throw new Error(`unexpected SQL in the page reads: ${q.slice(0, 120)}`);
+  },
+};
+
+// Sign-in is the one thing stubbed: the caller is whoever the header names.
+api.requireBuilder = (req, res, next) => {
+  req.builder = { id: String(req.headers['x-builder'] || F.ALICE.id), rank: 'thetes' };
+  next();
+};
+
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('lifecycle')) seams.registerProvider('lifecycle', require('../modules/lifecycle/lifecycle.js'));
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+
+const pageData = require('../modules/copy-desk/page-data.js');
+const express = require('express');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const buildRouter = require('../modules/copy-desk/routes/copy-desk.js');
+
+const app = express();
+app.use(attachFail);
+app.use(buildRouter());
+const server = await new Promise((resolve) => { const s = app.listen(0, '127.0.0.1', () => resolve(s)); });
+const base = `http://127.0.0.1:${server.address().port}`;
+
+async function get(p, builder) {
+  const r = await fetch(base + p, { headers: builder ? { 'x-builder': builder } : {} });
+  return { status: r.status, body: await r.json() };
+}
+
+// Three roots: both artifacts, the inventory alone, and nothing at all.
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'page-reads-'));
+const root = (name, files) => {
+  const dir = path.join(tmp, name);
+  fs.mkdirSync(path.join(dir, 'docs'), { recursive: true });
+  for (const [rel, v] of Object.entries(files)) fs.writeFileSync(path.join(dir, rel), JSON.stringify(v));
+  return dir;
+};
+const FULL = root('full', { 'docs/page-inventory.json': F.INVENTORY, 'docs/page-readings.json': F.READINGS });
+const INV_ONLY = root('inventory-only', { 'docs/page-inventory.json': F.INVENTORY });
+const EMPTY = root('empty', {});
+
+const { test, summary } = makeRunner();
+
+try {
+  pageData._setRoot(FULL);
+
+  await test('GET /copy-desk/pages: the three fixture cases, and the per-surface rollup', async () => {
+    const { status, body } = await get('/copy-desk/pages');
+    assert.equal(status, 200);
+    const p = (id) => body.pages.find((x) => x.id === id);
+    assert.equal(p('landing:index').status_label, 'Untweaked');
+    assert.equal(p('landing:projects').status_label, 'Text tweaked 2x');
+    assert.equal(p('landing:projects').drift.changed, false);
+    assert.equal(p('builders:studio').status_label, 'Text tweaked 1x');
+    assert.equal(p('builders:studio').drift.changed_count, 1);
+    assert.equal(p('builders:studio').open_round.state, 'writing');
+    assert.deepEqual(body.surfaces.map((s) => s.line), ['1 of 2 tweaked', '1 of 1 tweaked', '0 of 1 tweaked']);
+    assert.deepEqual(body.readings, { ok: true, at: 'docs/page-readings.json' });
+    assert.deepEqual(body.inventory, { at: 'docs/page-inventory.json' });
+  });
+
+  await test('GET /copy-desk/pages/:pageId: changelog, changed-since lines and the ships that changed them', async () => {
+    seen.length = 0;
+    const { status, body } = await get('/copy-desk/pages/builders:studio');
+    assert.equal(status, 200);
+    assert.deepEqual(body.changelog.map((c) => [c.task_id, c.artist.login, c.line_count]), [['201', 'alice', 1]]);
+    assert.deepEqual(body.drift.changed_lines, [{ key: 'L0002', section: 'greeting', text: 'Welcome back' }]);
+    assert.deepEqual(body.drift.ships.map((s) => s.task_id), ['555']);
+    assert.deepEqual(body.open_round.holder, { id: '8', login: 'bob' });
+    // The ships read is asked about THIS page's files, since THIS page's last round.
+    const ships = seen.find((s) => /t\.touches &&/.test(s.q));
+    assert.deepEqual(ships.params[0], F.STUDIO_FILES);
+    assert.equal(ships.params[1], '2026-09-20T10:00:00.000Z');
+
+    const twice = await get('/copy-desk/pages/landing:projects');
+    assert.deepEqual(twice.body.changelog.map((c) => c.artist.login), ['bob', 'alice']);
+    const untweaked = await get('/copy-desk/pages/landing:index');
+    assert.deepEqual([untweaked.body.count, untweaked.body.changelog.length, untweaked.body.drift.ships.length], [0, 0, 0]);
+  });
+
+  await test('an id the inventory does not know is unknown_page, never a blank page', async () => {
+    for (const id of ['landing:nope', 'not-an-id']) {
+      const { status, body } = await get(`/copy-desk/pages/${id}`);
+      assert.equal(status, 404, id);
+      assert.equal(body.error.code, 'unknown_page', id);
+    }
+  });
+
+  await test('GET /copy-desk/tally: the caller\'s own, through the reward port, 0 where no payout row exists yet', async () => {
+    seen.length = 0;
+    const alice = await get('/copy-desk/tally', F.ALICE.id);
+    assert.equal(alice.status, 200);
+    assert.equal(alice.body.credits, 60);
+    assert.equal(alice.body.pages_tweaked, 2);
+    assert.equal(alice.body.builder_id, '7');
+    assert.equal(alice.body.truncated, false);
+    const reads = seen.filter((s) => /FROM credit_log/.test(s.q));
+    assert.equal(reads.length, 1, 'one bounded ledger read, never a paging loop');
+    assert.equal(String(reads[0].params[0]), '7', 'the ledger is read for the CALLER');
+    const bob = await get('/copy-desk/tally', F.BOB.id);
+    assert.deepEqual([bob.body.credits, bob.body.this_week, bob.body.pages_tweaked], [0, 0, 1]);
+  });
+
+  await test('no readings: status still reads from the ledger, and drift says it does not know', async () => {
+    pageData._setRoot(INV_ONLY);
+    const { status, body } = await get('/copy-desk/pages');
+    assert.equal(status, 200);
+    assert.equal(body.readings.ok, false);
+    assert.equal(body.readings.code, 'page_readings_missing');
+    const studio = body.pages.find((x) => x.id === 'builders:studio');
+    assert.equal(studio.status_label, 'Text tweaked 1x');
+    assert.deepEqual([studio.drift.known, studio.drift.reason], [false, 'readings_missing']);
+  });
+
+  await test('no inventory: a named 503 with the command that fixes it, and the tally still answers', async () => {
+    pageData._setRoot(EMPTY);
+    for (const p of ['/copy-desk/pages', '/copy-desk/pages/landing:index']) {
+      const { status, body } = await get(p);
+      assert.equal(status, 503, p);
+      assert.equal(body.error.code, 'page_inventory_missing', p);
+      assert.equal(body.error.details.run, 'node scripts/gds/page-inventory.js', p);
+    }
+    const tally = await get('/copy-desk/tally', F.ALICE.id);
+    assert.equal(tally.status, 200);
+    assert.equal(tally.body.credits, 60);
+  });
+} finally {
+  pageData._setRoot(null);
+  server.close();
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+summary();

package/tests/page_reader.mjs

@@ -0,0 +1,200 @@
+// tests/page_reader.mjs — the page reader (BV2.TW04, task 1004315; ADR 0341 D3;
+// the Tweak Mode chain, goal 1000095).
+//
+// What these tests defend:
+//   1. NOTHING IS DROPPED. A visible string the copy registry cannot place is
+//      LISTED as unplaced, with a key and a section — the task's own done-when.
+//      Only a string that is nothing but the page's own data is left out, and
+//      the registry is always asked first, so a placed string is never mistaken
+//      for data.
+//   2. PLACEMENT. Exact text, a holed row's pattern, a segment of a holed row —
+//      a row in the page's own files first, never another page's html.
+//   3. SHARED. Shell text is marked shared, keeps its registry row when it has
+//      one, and is outside reading_hash.
+//   4. THE CONTRACT. docs/page-readings.json covers every inventory page, each
+//      line carries key/section/text/placement, keys run L0001.. in order, and
+//      both hashes are what the generator computes.
+//   5. FRESHNESS WITHOUT A BROWSER. --check compares files_hash, names the re-read
+//      command, and never loads the browser driver.
+//
+// DB-free, network-free, browser-free.
+// Run:  node --test tests/page_reader.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+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 reader = require(path.join(ROOT, 'scripts', 'gds', 'page-reader.js'));
+const shipCheck = require(path.join(ROOT, 'scripts', 'gds', 'ship-check.js'));
+
+const REGISTRY = {
+  entries: [
+    { id: 'aaa000000001', text: 'Welcome back', file: 'mods/pub/home.html', line: 10 },
+    { id: 'aaa000000002', text: '${…} of ${…} shipped this week', file: 'mods/pub/home.js', line: 40 },
+    { id: 'aaa000000003', text: 'Signed in as ${…}. Sign out', file: 'mods/pub/shell.js', line: 7 },
+    { id: 'aaa000000004', text: 'Welcome back', file: 'mods/pub/other.html', line: 3 },
+    { id: 'aaa000000005', text: 'Only on the other page', file: 'mods/pub/other.html', line: 5 },
+    { id: 'aaa000000006', text: 'Loaded late', file: 'mods/pub/late.js', line: 2 },
+    { id: 'aaa000000007', text: 'Studio — {{worldName}}', file: 'mods/pub/home.html', line: 1 },
+  ],
+};
+const PAGE = { id: 'builders:home', surface: 'builders', title: 'Home', files: ['mods/pub/home.html', 'mods/pub/shell.js', 'mods/pub/home.js'] };
+const matcher = reader.buildMatcher(REGISTRY);
+const place = (t) => reader.placeText(t, matcher, { files: PAGE.files, surfaceDir: 'mods/pub' });
+const fakeFs = { readFileSync: () => 'x' };
+const assemble = (captures, opts = {}) => reader.assembleReading(PAGE, captures, matcher, { surfaceDir: 'mods/pub', fsImpl: fakeFs, ...opts });
+
+test('an unplaced string is listed, not dropped', () => {
+  const r = assemble([{ state: 'default', strings: [
+    { text: 'Welcome back', section: 'Home', shared: null },
+    { text: 'A sentence no file in the registry holds', section: 'Home', shared: null },
+    { text: 'Welcome back', section: 'Later', shared: null },
+  ] }]);
+  const line = r.lines.find((l) => l.text === 'A sentence no file in the registry holds');
+  assert.ok(line, 'the unplaceable string is in the reading');
+  assert.equal(line.placement, 'unplaced');
+  assert.equal(line.section, 'Home');
+  assert.match(line.key, /^L\d{4}$/);
+  assert.equal(line.file, undefined, 'an unplaced line names no file');
+  assert.equal(r.counts.unplaced, 1);
+  assert.deepEqual(r.lines.map((l) => l.key), ['L0001', 'L0002', 'L0003'], 'keys run in page order');
+});
+
+test('an unplaced string that CONTAINS data keeps its words, with the data holed', () => {
+  const data = new Set(['Ada Lovelace', 'ready']);
+  const r = assemble([{ state: 'default', strings: [
+    { text: 'Good morning, Ada Lovelace', section: '', shared: null },
+    { text: 'Ada Lovelace', section: '', shared: null },
+    { text: '42', section: '', shared: null },
+  ] }], { dataValues: data });
+  assert.deepEqual(r.lines.map((l) => [l.text, l.placement]), [['Good morning, {…}', 'unplaced']]);
+  assert.equal(r.omitted.data, 1, 'the pure-data string is counted, and the number is not copy');
+});
+
+test('clock times and dates in an unplaced string are holed, so a re-read reads the same', () => {
+  assert.equal(reader.holeData('· since 10:43 PM', new Set()).text, '· since {…}');
+  assert.equal(reader.holeData('Filed Sep 10, 2026 · Blocking 2 tasks:', new Set()).text, 'Filed {…} · Blocking 2 tasks:');
+  assert.equal(reader.holeData('Jul 20, 2026', new Set()).data, true, 'a bare date is data');
+  assert.equal(reader.holeData('Licensed AGPL-3.0', new Set()).text, 'Licensed AGPL-3.0', 'a version number is left alone');
+});
+
+test('the registry is asked before the data: a placed string is never taken for data', () => {
+  const r = assemble([{ state: 'default', strings: [{ text: 'Welcome back', section: '', shared: null }] }], { dataValues: new Set(['Welcome back']) });
+  assert.equal(r.lines.length, 1);
+  assert.equal(r.lines[0].placement, 'placed');
+});
+
+test('placement: exact, pattern and segment; the page\'s own file wins; never another page\'s html', () => {
+  assert.deepEqual(place('Welcome back'), { file: 'mods/pub/home.html', line: 10, string_id: 'aaa000000001', text: 'Welcome back', how: 'exact' });
+  const pat = place('3 of 9 shipped this week');
+  assert.equal(pat.string_id, 'aaa000000002');
+  assert.equal(pat.text, '{…} of {…} shipped this week', 'a pattern-placed line reads as its row, with the registry\'s {…} holes');
+  assert.equal(place('shipped this week').string_id, 'aaa000000002', 'a literal segment of a holed row places');
+  assert.equal(place('Only on the other page'), null, 'a row in ANOTHER page\'s html does not place a string on this one');
+  assert.equal(place('Loaded late').file, 'mods/pub/late.js', 'a script elsewhere on the surface is the fallback');
+  assert.equal(place('Studio — Cloud Bongos').text, 'Studio — {{worldName}}', 'entities decode and a {{token}} is a hole');
+});
+
+test('shared text is marked shared, keeps its row, and stays out of reading_hash', () => {
+  const own = { text: 'Welcome back', section: 'Home', shared: null };
+  const a = assemble([{ state: 'default', strings: [{ text: 'Signed in as Ada. Sign out', section: '', shared: 'top bar' }, own] }]);
+  const top = a.lines[0];
+  assert.equal(top.placement, 'shared');
+  assert.equal(top.section, 'top bar');
+  assert.equal(top.string_id, 'aaa000000003');
+  const b = assemble([{ state: 'default', strings: [{ text: 'Something else entirely', section: '', shared: 'top bar' }, own] }]);
+  assert.equal(b.lines[0].placement, 'shared', 'an unplaceable shell string is still shared');
+  assert.equal(a.reading_hash, b.reading_hash, 'a changed shell line does not move the page\'s own hash');
+  const c = assemble([{ state: 'default', strings: [{ text: 'Welcome back', section: 'Elsewhere', shared: null }] }]);
+  assert.notEqual(a.reading_hash, c.reading_hash, 'a changed own line does');
+});
+
+test('other states add their lines where they sit, named, after the default state\'s', () => {
+  const r = assemble([
+    { state: 'closed', strings: [{ text: 'Welcome back', section: 'Home', shared: null }, { text: 'Loaded late', section: 'Home', shared: null }] },
+    { state: 'open', strings: [{ text: 'Welcome back', section: 'Home', shared: null }, { text: 'A panel only open shows', section: 'Home', shared: null }, { text: 'Loaded late', section: 'Home', shared: null }] },
+  ]);
+  assert.deepEqual(r.lines.map((l) => [l.text, l.state || null]), [['Welcome back', null], ['A panel only open shows', 'open'], ['Loaded late', null]]);
+  assert.deepEqual(r.states_read, ['closed', 'open']);
+});
+
+test('a string repeated in one section is one line with its occurrences', () => {
+  const r = assemble([{ state: 'default', strings: [1, 2, 3].map(() => ({ text: 'Welcome back', section: 'List', shared: null })) }]);
+  assert.equal(r.lines.length, 1);
+  assert.equal(r.lines[0].occurrences, 3);
+});
+
+test('files_hash folds CRLF, and moves when a file changes or disappears', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'page-reader-'));
+  fs.writeFileSync(path.join(dir, 'a.html'), 'one\ntwo\n');
+  const lf = reader.filesHash(['a.html'], { root: dir });
+  fs.writeFileSync(path.join(dir, 'a.html'), 'one\r\ntwo\r\n');
+  assert.equal(reader.filesHash(['a.html'], { root: dir }), lf, 'a Windows checkout agrees with CI');
+  fs.writeFileSync(path.join(dir, 'a.html'), 'one\ntwo!\n');
+  assert.notEqual(reader.filesHash(['a.html'], { root: dir }), lf);
+  fs.rmSync(path.join(dir, 'a.html'));
+  assert.notEqual(reader.filesHash(['a.html'], { root: dir }), lf);
+});
+
+test('checkReadings names a missing reading, a changed page and an extra one', () => {
+  const inv = { pages: [{ id: 's:a', files: ['x'] }, { id: 's:b', files: ['y'] }] };
+  const f = { readFileSync: (p) => (p.endsWith('x') ? 'X' : 'Y') };
+  const good = reader.filesHash(['x'], { fsImpl: f });
+  const stale = reader.checkReadings(inv, { pages: [{ id: 's:a', files_hash: good }, { id: 's:gone', files_hash: 'z' }] }, { fsImpl: f });
+  assert.deepEqual(stale, [{ id: 's:b', why: 'no reading' }, { id: 's:gone', why: 'not in the inventory' }]);
+  assert.deepEqual(reader.checkReadings(inv, { pages: [{ id: 's:a', files_hash: 'old' }, { id: 's:b', files_hash: reader.filesHash(['y'], { fsImpl: f }) }] }, { fsImpl: f }), [{ id: 's:a', why: 'its files changed' }]);
+});
+
+test('the committed readings cover every inventory page, in the D3 shape', () => {
+  const inv = JSON.parse(fs.readFileSync(path.join(ROOT, reader.INVENTORY_REL), 'utf8'));
+  const doc = JSON.parse(fs.readFileSync(path.join(ROOT, reader.READINGS_REL), 'utf8'));
+  assert.deepEqual(doc.pages.map((p) => p.id), inv.pages.map((p) => p.id), 'one reading per inventory page, in inventory order');
+  let unplaced = 0;
+  for (const p of doc.pages) {
+    assert.ok(p.lines.length > 0, `${p.id} has lines`);
+    p.lines.forEach((l, i) => {
+      assert.equal(l.key, `L${String(i + 1).padStart(4, '0')}`, `${p.id} keys run in order`);
+      assert.ok(typeof l.section === 'string' && l.section, `${p.id} ${l.key} has a section`);
+      assert.ok(typeof l.text === 'string' && l.text, `${p.id} ${l.key} has text`);
+      assert.ok(reader.PLACEMENTS.includes(l.placement), `${p.id} ${l.key} placement`);
+      if (l.placement === 'placed') assert.ok(l.file && Number.isInteger(l.line) && /^[0-9a-f]{12}$/.test(l.string_id), `${p.id} ${l.key} names its registry row`);
+      if (l.placement === 'unplaced') { unplaced += 1; assert.equal(l.string_id, undefined); }
+    });
+    assert.equal(p.reading_hash, reader.readingHash(p.lines), `${p.id} reading_hash is over its lines`);
+    assert.equal(p.counts.lines, p.lines.length);
+  }
+  assert.ok(unplaced > 0, 'the real pages carry unplaced strings, and they are listed');
+  assert.deepEqual(reader.checkReadings(inv, doc), [], 'the committed readings match this tree (re-read: node scripts/gds/page-reader.js --stale)');
+});
+
+test('--check needs no browser and names the re-read command', () => {
+  // A preload that makes the browser driver unloadable: if --check ever reached
+  // for it, this run would fail.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'page-reader-nobrowser-'));
+  const pre = path.join(dir, 'no-browser.cjs');
+  fs.writeFileSync(pre, "const M=require('module');const o=M._load;M._load=function(r,...a){if(/playwright|ui-design[\\\\/]kit/.test(r))throw new Error('browser reached: '+r);return o.call(this,r,...a);};\n");
+  const r = spawnSync(process.execPath, ['--require', pre, path.join(ROOT, 'scripts', 'gds', 'page-reader.js'), '--check'], { cwd: ROOT, encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr || r.stdout);
+  assert.match(reader.REREAD_COMMAND, /page-reader\.js --stale/);
+  const src = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'page-reader.js'), 'utf8');
+  assert.match(src, /Re-read them \(opens a browser\): \$\{REREAD_COMMAND\}/, 'a stale --check names the command');
+});
+
+test('ship-check runs the browser-free --check, and fitness does not render', () => {
+  const step = shipCheck.STEPS.find((s) => s.key === 'page-readings');
+  assert.ok(step, 'ship-check has a page-readings row');
+  assert.deepEqual(step.argv, ['scripts/gds/page-reader.js', '--check']);
+  assert.equal(step.fix, reader.REREAD_COMMAND);
+  const fitness = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'fitness.js'), 'utf8');
+  assert.doesNotMatch(fitness, /page-reader/, 'fitness never runs the reader (a render is the builder\'s own command)');
+});
+
+test('a hall page with no states file is read once, at its own path', () => {
+  assert.deepEqual(reader.planRenders({ id: 'builders:x', surface: 'builders', path: '/x', states_files: [] }).map((p) => [p.state, p.url]), [['default', '/x']]);
+});