@bongos/core 1.19.533 → 1.19.535

package/tests/catalog_only_client.mjs

@@ -0,0 +1,242 @@
+// tests/catalog_only_client.mjs — A CATALOG-ONLY CLIENT IS AN IDENTITY, NEVER A CREDENTIAL
+// (task 1003576, ADR 0246). The security half of the catalog bridge.
+//
+// The bridge mints an `platform_identity_sso_clients` row for EVERY control-plane project so
+// the map, the membership directory and `POST /projects/invite` have something to name — a
+// large increase in the number of registered clients. This file is the proof that the row it
+// mints can do nothing but be named: it carries an EMPTY secret_hash and an EMPTY
+// redirect-URI allow-list, and every SSO leg refuses it.
+//
+// Four of the five legs already fail closed on machinery that predates this task —
+// clientSecretValid() on a secretless client, redirectUriAllowed() on an empty allow-list —
+// and that is exactly why those are asserted here rather than assumed: they are load-bearing
+// for a decision made after they were written. The fifth, /sso/device/start, resolved a
+// client from a typed origin and checked NEITHER, so it grew an explicit guard.
+//
+// Also pinned: the invite route stops 404ing for a wizard-made project (task 1003580's
+// GAP 1). Its `project.curate` gate is untouched and is 1003580's own work.
+//
+// DB-free: the real routers driven over loopback, with the data-access functions stubbed on
+// the cached module objects (the provisioning_settings.mjs pattern).
+//
+// Run:  node --test --test-reporter=tap tests/catalog_only_client.mjs
+
+import assert from 'node:assert/strict';
+import { test, after } from 'node:test';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const pi = require('../modules/platform-identity/platform-identity.js');
+const catalog = require('../modules/platform-identity/project-catalog.js');
+const hubKeys = require('../modules/platform-identity/hub-keys.js');
+const hubDevice = require('../modules/platform-identity/hub-device.js');
+const api = require('../src/module-api.js');
+
+// The row the bridge writes: named, active, and holding nothing it could authenticate with.
+const CATALOG_ONLY = Object.freeze({
+  client_id: 'spike-harbor', secret_hash: '', name: 'spike-harbor',
+  redirect_uris: [], origin: 'https://spike-harbor.cloudbongos.test',
+  owner_github_id: 9001, status: 'active',
+});
+// A real federated client, for the contrast — the same shape with a credential.
+const FEDERATED = Object.freeze({
+  ...CATALOG_ONLY, client_id: 'mercury', secret_hash: 'a'.repeat(64),
+  redirect_uris: ['https://mercury.test/api/gds/auth/web/callback'], origin: 'https://mercury.test',
+});
+
+// ── the predicate itself ─────────────────────────────────────────────────────
+
+test('clientIsCredentialed separates "the hub can name it" from "it may sign people in"', () => {
+  assert.equal(catalog.clientIsCredentialed(FEDERATED), true);
+  assert.equal(catalog.clientIsCredentialed(CATALOG_ONLY), false);
+  for (const secret_hash of [null, undefined, '']) {
+    assert.equal(catalog.clientIsCredentialed({ ...FEDERATED, secret_hash }), false);
+  }
+  assert.equal(catalog.clientIsCredentialed(null), false, 'no client is not a credentialed one');
+});
+
+test('clientSecretValid fails closed on a secretless client, whatever is presented', () => {
+  // The load-bearing pre-existing guard: it hashes and constant-time-compares against a decoy
+  // when there is no real secret, then refuses because there was none. So the empty string,
+  // the literal decoy input and a lucky guess all lose.
+  for (const presented of ['', 'anything', 'a'.repeat(64), 'spike-harbor']) {
+    assert.equal(pi.clientSecretValid(CATALOG_ONLY, presented), false);
+  }
+  assert.equal(pi.clientSecretValid(FEDERATED, 'wrong'), false, 'and a real client still needs the real secret');
+});
+
+test('redirectUriAllowed fails closed on an empty allow-list', () => {
+  assert.equal(pi.redirectUriAllowed(CATALOG_ONLY, 'https://spike-harbor.cloudbongos.test/api/gds/auth/web/callback'), false);
+  assert.equal(pi.redirectUriAllowed(CATALOG_ONLY, ''), false);
+  assert.equal(pi.redirectUriAllowed(FEDERATED, FEDERATED.redirect_uris[0]), true);
+});
+
+// ── the routes, executed ─────────────────────────────────────────────────────
+
+// The auth middleware is DESTRUCTURED off the doorway at route-module load, so these stubs
+// have to be in place before the routers are required.
+api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'curator', rank: 'metic' }; next(); };
+api.requirePermission = () => (_req, _res, next) => next();
+
+const express = require('express');
+const ssoRoutes = require('../modules/platform-identity/routes/sso.js');
+const projectsRoutes = require('../modules/platform-identity/routes/projects.js');
+
+// The routes read the hub's own config through these; the SSO legs 503 without them, which
+// would hide the refusals under test.
+hubKeys.hubSigningConfigured = () => true;
+hubKeys.hubPublicKeyB64 = () => 'stub-public-key';
+hubDevice.hubDeviceConfigured = () => true;
+let deviceStarts = 0;
+hubDevice.startHubGithubDevice = async () => { deviceStarts++; return { device_code: 'd', user_code: 'U' }; };
+
+// The client registry, stubbed on the cached module object.
+const CLIENTS = new Map([[CATALOG_ONLY.client_id, CATALOG_ONLY], [FEDERATED.client_id, FEDERATED]]);
+pi.getClient = async (id) => CLIENTS.get(id) || null;
+pi.getClientByOrigin = async (origin) => {
+  const norm = String(origin || '').replace(/\/+$/, '');
+  return [...CLIENTS.values()].find((c) => c.origin === norm && c.status === 'active') || null;
+};
+// The invite leg's two other reads — the point is which refusal the route reaches, not what
+// a real membership write does.
+pi.getAccountByLogin = async (login) => (login === 'ghost' ? null : { github_id: 5150, github_login: login });
+pi.inviteToProject = async ({ clientId, githubId }) => ({ invited: true, clientId, githubId });
+
+const app = express();
+app.use(express.json());
+app.use((_req, res, next) => {
+  res.fail = (code, opts, details) => {
+    const status = typeof opts === 'number' ? opts : (opts && opts.status) || 400;
+    res.status(status).json({ error: { code, ...(typeof opts === 'object' ? opts : {}), ...(details || {}) } });
+  };
+  next();
+});
+app.use('/api/bongos', ssoRoutes());
+app.use('/api/bongos', projectsRoutes());
+
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+after(() => server.close());
+
+function call(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = body === undefined ? null : JSON.stringify(body);
+    const req = http.request(`${base}${path}`, {
+      method,
+      headers: payload ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) } : {},
+    }, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; });
+      res.on('end', () => { let j = null; try { j = JSON.parse(d); } catch { /* html */ } resolve({ status: res.statusCode, body: j, raw: d }); });
+    });
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+test('/sso/authorize REFUSES a catalog-only client — no redirect_uri is registered for it', async () => {
+  // The open-redirect guard doing double duty: an empty allow-list means every candidate
+  // callback fails exact match, so the browser leg never mints a code and never redirects.
+  const uri = 'https://spike-harbor.cloudbongos.test/api/gds/auth/web/callback';
+  const res = await call('GET', `/sso/authorize?client_id=spike-harbor&redirect_uri=${encodeURIComponent(uri)}`);
+  assert.equal(res.status, 400);
+  assert.match(res.raw, /redirect_uri is not registered/);
+  assert.doesNotMatch(res.raw, /code=/, 'no authorization code may appear on any refusal path');
+});
+
+test('/sso/token REFUSES a catalog-only client for every secret it could be handed', async () => {
+  for (const client_secret of ['', 'guess', 'spike-harbor', 'a'.repeat(64)]) {
+    const res = await call('POST', '/sso/token', {
+      client_id: 'spike-harbor', client_secret: client_secret || 'x',
+      code: 'c', redirect_uri: 'https://spike-harbor.cloudbongos.test/api/gds/auth/web/callback',
+    });
+    assert.equal(res.status, 401, `secret "${client_secret}" must not exchange`);
+    assert.equal(res.body.error.code, 'invalid_client');
+  }
+});
+
+test('/sso/device/start REFUSES a catalog-only origin — the leg that checked neither guard', async () => {
+  // This is the ONE that needed new code. It resolves the client from the USER-TYPED origin
+  // and checked only `status`, so without the guard every catalogued project would have had a
+  // device flow nobody registered a credential for.
+  deviceStarts = 0;
+  const res = await call('POST', '/sso/device/start', { origin: 'https://spike-harbor.cloudbongos.test' });
+  assert.equal(res.status, 401);
+  assert.equal(res.body.error.code, 'invalid_client');
+  assert.equal(deviceStarts, 0, 'and the GitHub device flow is never even started');
+});
+
+test('/sso/device/start still serves a real federated client', async () => {
+  // The guard must refuse the new row shape and nothing else.
+  deviceStarts = 0;
+  const res = await call('POST', '/sso/device/start', { origin: 'https://mercury.test' });
+  assert.equal(res.status, 200);
+  assert.equal(res.body.user_code, 'U');
+  assert.equal(deviceStarts, 1);
+});
+
+test('/sso/membership/check-in REFUSES a catalog-only client', async () => {
+  const res = await call('POST', '/sso/membership/check-in', {
+    client_id: 'spike-harbor', client_secret: 'x', github_id: 5150, github_login: 'someone',
+  });
+  assert.equal(res.status, 401);
+  assert.equal(res.body.error.code, 'invalid_client');
+});
+
+test('/sso/activity/rollup REFUSES a catalog-only client', async () => {
+  const res = await call('POST', '/sso/activity/rollup', {
+    client_id: 'spike-harbor', client_secret: 'x', github_id: 5150, credits: 999, rank: 'archon',
+  });
+  assert.equal(res.status, 401);
+  assert.equal(res.body.error.code, 'invalid_client');
+});
+
+// ── what the catalog row DOES buy: a resolvable invite target (task 1003580) ──
+
+test('POST /projects/invite no longer 404s for a wizard-made project', async () => {
+  // GAP 1 of task 1003580: the route resolves its target with getClient() and refused
+  // `unknown_project` because a standalone project was never an sso_clients row at all. It
+  // now is. The route's `project.curate` gate is deliberately untouched — widening it to the
+  // project's own owner is 1003580's job, and this test stubs the permission middleware so
+  // the assertion is about the TARGET resolving, not about who may call it.
+  const res = await call('POST', '/projects/invite', { client_id: 'spike-harbor', github_login: 'someone' });
+  assert.notEqual(res.status, 404);
+  assert.equal(res.status, 201);
+  assert.equal(res.body.invited, true);
+  assert.equal(res.body.clientId, 'spike-harbor');
+});
+
+test('an unknown project still 404s — the catalog row is what resolves, not the route', async () => {
+  const res = await call('POST', '/projects/invite', { client_id: 'never-provisioned', github_login: 'someone' });
+  assert.equal(res.status, 404);
+  assert.equal(res.body.error.code, 'unknown_project');
+});
+
+// ── the seam the write half travels on ───────────────────────────────────────
+
+test('mounting the projects routes registers the `project.catalog` port', async () => {
+  // The write half of the same seam `project.publishGate` is the read half of. provisioning
+  // owns these projects and may not import this module (ADR 0083), so the switchboard is how
+  // the projection reaches the tables that hold the map.
+  assert.equal(api.hasProvider('project.catalog'), true);
+  assert.equal(api.resolve('project.catalog'), catalog.projectCatalogPort);
+  assert.equal(typeof api.resolve('project.catalog').publish, 'function');
+  assert.ok(Object.isFrozen(catalog.projectCatalogPort), 'a consumer must not be able to re-point the port');
+});
+
+test('the port declares the catalog write and nothing else', () => {
+  // One verb. A consumer maps its own row onto the entry shape, so the catalog never learns
+  // another module’s schema and no module gets a general-purpose handle on these tables.
+  assert.deepEqual(Object.keys(catalog.projectCatalogPort), ['publish']);
+});
+
+test('the module manifest DECLARES the port it registers', async () => {
+  // verifyPortsSatisfied reads the manifests at boot, not the registry — an undeclared
+  // provider is invisible to it.
+  const manifest = JSON.parse(await (await import('node:fs/promises')).readFile(
+    new URL('../modules/platform-identity/module.json', import.meta.url), 'utf8'));
+  assert.ok(manifest.provides.includes('project.catalog'));
+});

package/tests/currency_label.mjs

@@ -48,11 +48,14 @@ test('R57: clientBranding exposes theme.ui (web), NOT theme.palette (server-only
 });
 
 test('clientBranding exposes project policy — the settings read-back (task 1003140), defaulting to today\'s behavior', () => {
-  // `visibility` — the join door — joined the block in task 1002324 (ADR 0182 D1)
-  assert.deepEqual(clientBranding({}).project, { platformVisibility: 'public', joinability: 'apply', visibility: 'public' });
+  // `visibility` — the join door — joined the block in task 1002324 (ADR 0182 D1);
+  // `joinGrant` — what a PUBLIC join grants — in task 1002331 (ADR 0247), defaulting
+  // to `full`, the value that narrows nothing, so an un-pushed instance is unchanged
+  assert.deepEqual(clientBranding({}).project,
+    { platformVisibility: 'public', joinability: 'apply', visibility: 'public', joinGrant: 'full' });
   assert.deepEqual(
-    clientBranding({ project: { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth' } }).project,
-    { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth' },
+    clientBranding({ project: { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth', joinGrant: 'view' } }).project,
+    { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth', joinGrant: 'view' },
     'what the instance actually resolved (env override included) is what it publishes');
 });
 
@@ -71,7 +74,7 @@ test('clientBranding is a SMALL allow-list — no server-only field leaks to the
   // `project` joined the allow-list in task 1003140: the per-project policy is public
   // by nature and is the settings read-back a manage page needs (see clientBranding).
   assert.deepEqual(Object.keys(projected).sort(), ['copy', 'currency', 'identity', 'project', 'rankLabels', 'reward', 'theme']);
-  assert.deepEqual(Object.keys(projected.project).sort(), ['joinability', 'platformVisibility', 'visibility']);
+  assert.deepEqual(Object.keys(projected.project).sort(), ['joinGrant', 'joinability', 'platformVisibility', 'visibility']);
   for (const leak of ['domains', 'repo', 'db', 'envPrefix', 'llmProjectName']) {
     assert.equal(projected[leak], undefined, `${leak} must not reach the client`);
   }

package/tests/hall_kit_charts.mjs

@@ -349,6 +349,10 @@ test('the kit is loaded before every page that draws through it', () => {
     ['index.html', 'hall-render.js'],
     ['watch.html', 'watch.js'],
     ['profile.html', 'profile-charts.js'],
+    // task 1003447: the roadmap's own series module reads the kit, and the page
+    // reads that. Both edges of the chain are ordered here.
+    ['roadmap.html', 'roadmap-timeline.js'],
+    ['roadmap.html', 'roadmap.js'],
   ]) {
     // The loaded ORDER, read off the script tags — index.html's prose mentions
     // hall-render.js ~90 lines above where it loads it, so a substring search
@@ -375,3 +379,172 @@ test('the migrated pages run for real against the kit and emit its classes', ()
     /class="kit-bars"/,
   );
 });
+
+// ---- 5. the SPAN bar and the fitted axis (task 1003447) --------------------
+//
+// Two options, both added so the goal's last two charts needed no new drawing
+// code and no new class family: a bar that starts somewhere other than the
+// track's left edge (which is what makes a bar series a TIMELINE), and a plot
+// whose axis sits at something other than zero (which is what makes a step line
+// readable for a LEVEL rather than a running total).
+
+test('a row\'s `start` offsets the bar and leaves its length alone', () => {
+  // The roadmap's shape: version A ran for the first quarter of the axis,
+  // version B for the middle half. Same primitive, same classes.
+  const html = kit.barSeriesHtml([
+    { label: 'A', value: 25 },
+    { label: 'B', value: 50, start: 25 },
+  ], { max: 100 });
+  const fills = [...html.matchAll(/class="kit-bars__fill" style="([^"]+)"/g)].map((m) => m[1]);
+  assert.deepEqual(fills, ['width:25%', 'margin-left:25%;width:50%']);
+  assert.equal((html.match(/class="kit-bars"/g) || []).length, 1, 'still one class family');
+});
+
+test('a bar with no `start` writes no offset at all', () => {
+  // The compatibility contract: every caller that predates the span option gets
+  // byte-identical markup, so `margin-left:0%` never appears in a diff or in a
+  // snapshot of an existing chart.
+  const html = kit.barSeriesHtml([{ label: 'a', value: 3 }, { label: 'b', value: 1, start: 0 }]);
+  assert.doesNotMatch(html, /margin-left/);
+  // A nonsense start is ignored rather than written through into the style.
+  const junk = kit.barSeriesHtml([{ label: 'a', value: 3, start: 'nope' }], { max: 10 });
+  assert.doesNotMatch(junk, /margin-left/);
+  assert.doesNotMatch(junk, /NaN/);
+});
+
+test('a tiny non-zero `start` still offsets, so "first" stays a real claim', () => {
+  // The offset takes the same floor the width does. Without it a span beginning
+  // just after the axis origin rounds to 0% and draws flush left — which on a
+  // timeline reads as "this one started first", a claim about ordering rather
+  // than a rounding artefact.
+  const html = kit.barSeriesHtml([
+    { label: 'first', value: 500 },
+    { label: 'barely later', value: 500, start: 1 },
+  ], { max: 1000 });
+  const fills = [...html.matchAll(/class="kit-bars__fill" style="([^"]+)"/g)].map((m) => m[1]);
+  assert.equal(fills[0], 'width:50%', 'the one at the origin carries no offset');
+  assert.match(fills[1], /^margin-left:1%/, 'and the one after it is visibly after it');
+});
+
+test('a positive value never draws nothing, however small its share', () => {
+  // Rounding alone sends anything under half a percent to `width:0%`, which
+  // reads as "none" — the one thing it is not. Load-bearing for the roadmap: a
+  // version that started and shipped inside one day is a real span.
+  const html = kit.barSeriesHtml([{ label: 'tiny', value: 1 }, { label: 'huge', value: 100000 }]);
+  assert.match(html, /width:1%/, 'the sliver survives');
+  // and zero is still zero: an empty track is the honest picture of nothing.
+  assert.match(kit.barSeriesHtml([{ label: 'a', value: 0 }, { label: 'b', value: 9 }]), /width:0%/);
+});
+
+test('plotWindow puts a reachable-zero series on a zero floor', () => {
+  const w = kit.plotWindow([0, 3, 1, 4]);
+  assert.equal(w.yMin, 0, 'a count sits on zero — the distance from it IS the reading');
+  assert.ok(w.yMax > 4, 'with air above, so the peak does not ride the top edge');
+  assert.equal(w.lo, 0);
+  assert.equal(w.hi, 4);
+});
+
+test('plotWindow fits the floor for a level, which is why the caller must say so', () => {
+  const w = kit.plotWindow([24880, 27195], { zeroBased: false });
+  assert.ok(w.yMin > 24000 && w.yMin < 24880, 'the axis rises to just under the minimum');
+  assert.ok(w.yMax > 27195);
+  // The whole point: on a zero floor this month of change would occupy the top
+  // 9% of the box. Fitted, it occupies the whole of it.
+  const zero = kit.plotWindow([24880, 27195]);
+  assert.ok((w.yMax - w.yMin) < (zero.yMax - zero.yMin) / 5, 'the fitted window is far tighter');
+});
+
+test('plotWindow survives a flat series and an empty one', () => {
+  // A flat series has no range to take a fraction of, and dividing by it is how
+  // a chart renders as an invisible NaN.
+  const flat = kit.plotWindow([5, 5, 5]);
+  assert.ok(flat.yMax > 5, 'flat still gets air, so the line is not welded to the top');
+  const flatFit = kit.plotWindow([5, 5, 5], { zeroBased: false });
+  assert.ok(flatFit.yMin < 5 && flatFit.yMax > 5, 'and a fitted flat line lands mid-box');
+  const zeros = kit.plotWindow([0, 0, 0]);
+  assert.equal(zeros.yMin, 0);
+  assert.ok(zeros.yMax > 0, 'a month of honest zeros still divides by something');
+  assert.deepEqual(kit.plotWindow([]), { lo: 0, hi: 0, yMin: 0, yMax: 1, n: 0 });
+});
+
+test('plotWindow DROPS a non-finite reading rather than counting it as zero', () => {
+  // The trap this exists to close: Number(null) is 0 and finite, so a snapshot
+  // that predates a column would drag `lo` to zero and draw a cliff.
+  const w = kit.plotWindow([100, null, 120, undefined, 110]);
+  assert.equal(w.lo, 100);
+  assert.equal(w.n, 3, 'three readings, not five');
+});
+
+test('yMin lifts the axis, and its default leaves every existing series where it was', () => {
+  const box = { width: 100, height: 100, pad: { l: 0, r: 0, t: 0, b: 0 } };
+  const pts = [{ x: 0, value: 10 }, { x: 10, value: 20 }];
+  // Default (0): 20 of a 20-high window is the top, 10 is halfway.
+  const zero = kit.timeStepGeometry(pts, { x0: 0, x1: 10, yMax: 20, ...box });
+  assert.equal(zero.py(20).toFixed(1), '0.0');
+  assert.equal(zero.py(10).toFixed(1), '50.0');
+  // Fitted to 10..20: the same two points now span the whole box.
+  const fitted = kit.timeStepGeometry(pts, { x0: 0, x1: 10, yMin: 10, yMax: 20, ...box });
+  assert.equal(fitted.py(20).toFixed(1), '0.0');
+  assert.equal(fitted.py(10).toFixed(1), '100.0');
+  // A degenerate window (yMin === yMax) must not divide by zero.
+  const flat = kit.timeStepGeometry(pts, { x0: 0, x1: 10, yMin: 5, yMax: 5, ...box });
+  assert.doesNotMatch(flat.d, /NaN|Infinity/);
+});
+
+test('RUN: the roadmap timeline draws the real versions as spans on one axis', async () => {
+  // The page's own series module, run against the checked-in /public/versions
+  // fixture — the arithmetic a source assertion cannot reach. It is imported
+  // rather than stubbed for the same reason the kit is: a copy of the maths
+  // agreeing with itself proves nothing about what a reader gets.
+  const modPath = path.join(HALL, 'roadmap-timeline.js');
+  const tl = await import(`file://${modPath.replace(/\\/g, '/')}`).then((m) => m.default);
+  // public__versions.json, NOT versions.json — the deck calls /public/versions,
+  // and the authenticated list is a different payload. Reading the wrong one
+  // here is precisely the trap this task's own CLAUDE.md note warns about.
+  const fixture = JSON.parse(fs.readFileSync(
+    path.join(ROOT, 'scripts', 'hall-preview', 'fixtures', 'public__versions.json'), 'utf8'));
+  const all = fixture.versions.map((v) => ({ id: v.id, start: v.started_at, ship: v.shipped_at }));
+  const now = Date.parse('2026-09-03T12:00:00Z');
+
+  const rows = tl.timelineRows(all, now);
+  assert.equal(rows.length, all.length, 'every fixture version has a start date');
+  const starts = rows.map((r) => r.from);
+  assert.deepEqual(starts, [...starts].sort((a, b) => a - b), 'oldest first');
+  assert.ok(rows.some((r) => r.open), 'the in-flight version runs to today');
+  assert.ok(rows.every((r) => r.to >= r.from), 'no span runs backwards');
+
+  const card = tl.timelineCardHtml(all, now, kit);
+  assert.equal(card.count, rows.length);
+  assert.doesNotMatch(card.html, /NaN|Infinity|undefined/);
+  assert.match(card.html, /class="kit-bars"/, 'drawn by the kit, not by hand');
+  const offsets = [...card.html.matchAll(/margin-left:(\d+)%/g)].map((m) => Number(m[1]));
+  assert.ok(offsets.length >= 2, 'later versions start further along the axis');
+  assert.deepEqual(offsets, [...offsets].sort((a, b) => a - b), 'and their offsets grow with their start dates');
+  // PMS-V1 started and shipped inside ONE day of a four-month axis: the span
+  // that rounds to nothing without the 1% floor. It is also the earliest
+  // version, so it correctly carries no offset — assert the floor, not a
+  // margin-left the axis origin has no reason to write.
+  const pms = card.html.match(/PMS-V1<\/span><span class="kit-bars__track"[^>]*><span class="kit-bars__fill" style="([^"]+)"/);
+  assert.ok(pms, 'PMS-V1 has a bar');
+  assert.match(pms[1], /width:[1-9]/, 'a one-day span still draws, rather than rounding to nothing');
+  assert.doesNotMatch(pms[1], /margin-left/, 'and the earliest version sits at the axis origin');
+});
+
+test('RUN: the timeline refuses to draw rather than drawing an empty axis', async () => {
+  const modPath = path.join(HALL, 'roadmap-timeline.js');
+  const tl = await import(`file://${modPath.replace(/\\/g, '/')}`).then((m) => m.default);
+  const now = Date.parse('2026-09-03T12:00:00Z');
+  assert.equal(tl.timelineCardHtml([], now, kit), null, 'nothing at all');
+  assert.equal(tl.timelineCardHtml([{ id: 'A', start: '2026-01-01' }], now, kit), null,
+    'one version is not a timeline');
+  // A version with no start date is left OUT and counted in the foot, never
+  // drawn at the axis origin — which would read as "began with the project".
+  const card = tl.timelineCardHtml([
+    { id: 'A', start: '2026-01-01', ship: '2026-02-01' },
+    { id: 'B', start: '2026-03-01', ship: null },
+    { id: 'C', start: null, ship: null },
+  ], now, kit);
+  assert.equal(card.count, 2);
+  assert.doesNotMatch(card.html, />C</, 'the unstarted version is not a bar');
+  assert.match(card.html, /1 version with no start date is not shown/, 'the foot says so');
+});

package/tests/hall_oversight_world.mjs

@@ -11,6 +11,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import path from 'node:path';
+import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -116,3 +117,161 @@ test('the vocabulary wall holds: the family is named oversight on the government
     assert.ok(!/governance/i.test(read(f)), `${f} does not say the pre-ADR-0174 word`);
   }
 });
+
+// ---- the repo-health trend (task 1003447, `legibility-series-are-drawn`) ----
+//
+// /public/repo-health has always answered with `latest` PLUS a trend[], and the
+// route's own comment says the trend exists "so the status page can draw LOC /
+// dead-exports / stale-branch lines over time ... oldest->newest so the
+// dashboard can plot left->right". Watch requested it WITH ?days=30 — paying for
+// the whole window — and renderLedger read one snapshot off it. The series
+// arrived over the wire and went on the floor.
+//
+// The AXIS arithmetic is the kit's (plotWindow / timeStepSeriesHtml) and
+// tests/hall_kit_charts.mjs runs it for real. What lives here is Watch's half:
+// that the section composes the kit rather than drawing by hand, and — the part
+// no source assertion can reach — that booting the REAL page against the REAL
+// checked-in fixture puts four finite plots on the panel.
+
+const FIXTURES = path.join(ROOT, 'scripts', 'hall-preview', 'fixtures');
+const repoHealthFixture = () => JSON.parse(fs.readFileSync(path.join(FIXTURES, 'public__repo-health.json'), 'utf8'));
+
+// Boot watch.js in a stub DOM with the real dom-utils and the real kit, answer
+// /me as an archon and /public/repo-health with the fixture, and hand back what
+// landed in #ledger-trend. Every OTHER endpoint answers 500, which is the
+// page's own design (each section loads independently) and keeps this harness
+// to the one panel it is about.
+async function bootWatchLedger(overrides = {}) {
+  const payload = { ...repoHealthFixture(), ...overrides };
+  const els = new Map();
+  const makeEl = () => ({
+    dataset: {}, style: {}, textContent: '', hidden: false, disabled: false, _html: '',
+    classList: { add() {}, remove() {}, toggle() { return false; }, contains() { return false; } },
+    setAttribute() {}, getAttribute() { return null; }, removeAttribute() {},
+    addEventListener() {}, appendChild() {}, insertAdjacentHTML(_, h) { this._html += h; },
+    closest() { return null; },
+    querySelector() { return null; }, querySelectorAll() { return []; },
+    set innerHTML(v) { this._html = String(v); }, get innerHTML() { return this._html; },
+  });
+  const documentObj = {
+    getElementById(id) { if (!els.has(id)) els.set(id, makeEl()); return els.get(id); },
+    querySelector(sel) {
+      const s = String(sel);
+      return s.startsWith('#') ? this.getElementById(s.slice(1)) : makeEl();
+    },
+    querySelectorAll() { return []; },
+    createElement() { return makeEl(); },
+    addEventListener() {},
+  };
+  const client = {
+    request: async (method, urlPath) => {
+      if (urlPath.endsWith('/me')) {
+        return { ok: true, status: 200, data: { builder: { id: '1', rank: 'archon', github_login: 'x' } } };
+      }
+      if (urlPath.includes('/public/repo-health')) return { ok: true, status: 200, data: payload };
+      return { ok: false, status: 500, data: {} };
+    },
+  };
+  const windowObj = {
+    BongosClient: { createClient: () => client },
+    __BRANDING__: {}, __MODULES__: { enabled: {} },
+    localStorage: { getItem: () => null, setItem() {}, removeItem() {} },
+    location: { hash: '', pathname: '/watch', search: '', assign() {} },
+    addEventListener() {}, matchMedia: () => ({ matches: false, addEventListener() {} }),
+  };
+  const sandbox = {
+    window: windowObj, document: documentObj, location: windowObj.location,
+    localStorage: windowObj.localStorage,
+    // The two browser globals the kit reaches for outside `window`: CSS.escape
+    // (tab selectors) and history.replaceState (the tab's deep link).
+    CSS: { escape: (s) => String(s) },
+    history: { replaceState() {} },
+    console: { ...console, error() {}, warn() {} },
+    setTimeout, clearTimeout, URLSearchParams, Intl,
+  };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  for (const f of ['dom-utils.js', 'hall-kit.js', 'watch.js']) {
+    vm.runInContext(read(f), sandbox, { filename: f });
+  }
+  // load() is async: let every section's promise settle before reading the DOM.
+  for (let i = 0; i < 8; i++) await new Promise((r) => setTimeout(r, 0));
+  return { html: documentObj.getElementById('ledger-trend').innerHTML, latest: payload.latest, windowObj };
+}
+
+test('the repo-health trend has a mount, and renderLedger fills it', () => {
+  const js = read('watch.js');
+  assert.match(read('watch.html'), /id="ledger-trend"/, 'the mount exists in the markup');
+  assert.match(js, /renderTrend\(data\);/, 'renderLedger hands the whole payload on, not just latest');
+  assert.match(js, /'\/public\/repo-health\?days=30'/, 'the request still asks for the window');
+  assert.match(js, /data\.window_days/, 'and the heading says which window it drew');
+});
+
+test('every mark in the trend is the kit\'s — no hand-drawn plot on the oversight page', () => {
+  const js = read('watch.js');
+  for (const fn of ['plotWindow', 'timeStepSeriesHtml', 'plotSvgHtml', 'plotValueLabelHtml']) {
+    assert.match(js, new RegExp(`kit\\.${fn}\\(`), `the trend draws through ${fn}`);
+  }
+  // §6b holds this globally; pinned here too because this is the page that
+  // hand-rolled a bar chart once already (task 1003445).
+  assert.doesNotMatch(js, /<(?:path|polyline|rect)\b[^>]*\b(?:d|points)="\$\{/,
+    'no hand-built SVG geometry on Watch');
+  // No readout is wired, so the plot must drop the focus stop AND the crosshair
+  // together — the task 1003446 pairing. Half of it is worse than neither.
+  assert.match(js, /interactive: false/, 'the trend plots are not fake-interactive');
+  assert.match(js, /class="pchart__twin"/, 'and each carries its table twin instead');
+});
+
+test('a fitted axis says so in words, because it magnifies every move', () => {
+  // total_loc is the one metric drawn off a non-zero floor: on a zero floor a
+  // month of real change is a flat band across the top of the box. That choice
+  // makes small movement look large, so the figure states its baseline rather
+  // than letting the picture imply a collapse to nothing.
+  const js = read('watch.js');
+  assert.match(js, /key: 'total_loc',[\s\S]{0,120}zeroBased: false/, 'total_loc fits its floor');
+  for (const k of ['dead_exports', 'stale_branches', 'confirmed_unshipped']) {
+    assert.match(js, new RegExp(`key: '${k}',[\\s\\S]{0,120}zeroBased: true`), `${k} keeps the zero floor`);
+  }
+  assert.match(js, /not zero/, 'and a fitted figure names its baseline in the foot');
+});
+
+test('RUN: the real page against the real fixture puts four finite plots on the panel', async () => {
+  // The half a source assertion cannot see. A NaN in a path `d` renders as an
+  // invisible chart with no error anywhere — a grep never finds that, and a
+  // stub agreeing with a stub never would either.
+  const { html, latest } = await bootWatchLedger();
+  assert.ok(html.length > 0, 'the panel drew something');
+  assert.doesNotMatch(html, /NaN|Infinity|undefined/, 'no broken geometry reaches the DOM');
+  const figures = [...html.matchAll(/id="ledger-trend-([a-z_]+)"/g)].map((m) => m[1]);
+  assert.deepEqual(figures, ['total_loc', 'dead_exports', 'stale_branches', 'confirmed_unshipped'],
+    'all four metrics draw, in the reading order');
+  assert.equal((html.match(/class="kit-plot"/g) || []).length, 4, 'four plots');
+  assert.ok(!/tabindex="0"/.test(html), 'none of them is a focus stop with nothing to do');
+  assert.equal((html.match(/class="kit-plot__hair"/g) || []).length, 0, 'and none carries a crosshair nothing moves');
+  // The plot and the figure band above it derive from ONE payload, so they
+  // cannot disagree: the labelled endpoint is the number the snapshot states.
+  const compact = `${(latest.total_loc / 1e3).toFixed(1)}k`;
+  assert.ok(html.includes(`>${compact}<`), `the line ends on ${compact}, the value the snapshot figure shows`);
+});
+
+test('RUN: a payload with no trend renders nothing rather than an empty panel', async () => {
+  // The honest exit the module doc requires. The figures above already say what
+  // today's numbers are; an empty card under them would be worse than no card.
+  const { html } = await bootWatchLedger({ trend: [] });
+  assert.equal(html.trim(), '', 'no heading, no card, no "no data" box');
+});
+
+test('RUN: one snapshot is a reading, not a trend', async () => {
+  // A single point draws a dot on an axis with nothing to compare it to.
+  const { html } = await bootWatchLedger({ trend: repoHealthFixture().trend.slice(-1) });
+  assert.equal(html.trim(), '');
+});
+
+test('RUN: a metric its snapshots never carried is skipped, not drawn as a cliff', async () => {
+  // An older snapshot predates a column and sends null. Reading that as 0 would
+  // draw a fall to the floor that never happened, so the figure is dropped.
+  const trend = repoHealthFixture().trend.map((r) => ({ ...r, dead_exports: null }));
+  const { html } = await bootWatchLedger({ trend });
+  const figures = [...html.matchAll(/id="ledger-trend-([a-z_]+)"/g)].map((m) => m[1]);
+  assert.deepEqual(figures, ['total_loc', 'stale_branches', 'confirmed_unshipped']);
+});