@bongos/core 1.19.946 → 1.19.947

package/tests/goal_graph.mjs

@@ -0,0 +1,192 @@
+// tests/goal_graph.mjs — GET /goals/graph, the data under the goal map (task
+// 1003479, goal 1000089, ADR 0227 §6 item 3 + §10.4).
+//
+// The endpoint is an AGGREGATE: one node per goal, one edge per ordered pair of
+// goals whose tasks depend on each other. What this file pins is the part a
+// reader cannot see from the picture — that the shape is right (a count of goals
+// is not a count of task edges), that a private goal is redacted rather than
+// dropped, that no task id or title can leave the query, and that the identity
+// deciding all of it comes from the authenticated request.
+//
+// DB-free: the pure shaper is run directly, the SQL is run against a recording
+// fake pool, and the handler against stub collaborators (the goal-category.js
+// handler-factory precedent).
+//
+// Run:  node tests/goal_graph.mjs
+process.env.NODE_ENV = 'test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { shapeGraph, goalGraphRows, goalGraph, goalGraphHandler } = require(path.join(ROOT, 'modules/lifecycle/goal-graph.js'));
+const { DONE_STATUSES, CUT_STATUSES } = require(path.join(ROOT, 'modules/lifecycle/task-status.js'));
+const GOALS_ROUTE = fs.readFileSync(path.join(ROOT, 'modules/lifecycle/routes/goals.js'), 'utf8');
+const GRAPH_SRC = fs.readFileSync(path.join(ROOT, 'modules/lifecycle/goal-graph.js'), 'utf8');
+
+const { test, summary } = makeRunner();
+
+const CATS = new Map([['7', { id: 7, slug: 'security', label: 'Security' }]]);
+const g = (id, extra = {}) => ({ goal_id: String(id), title: `Goal ${id}`, status: 'open', version_id: 'V1', category_id: null, visible: true, task_total: 4, task_done: 1, ...extra });
+const e = (from, to, count = 1) => ({ from_goal_id: String(from), to_goal_id: String(to), count });
+
+// ---- shapeGraph --------------------------------------------------------------
+
+await test('an edge means "from waits on to", and each node counts DISTINCT goals, not task edges', () => {
+  const out = shapeGraph({ goals: [g(1), g(2), g(3)], edges: [e(1, 2, 9), e(1, 3, 1), e(3, 2, 2)] });
+  const by = Object.fromEntries(out.nodes.map((n) => [n.goal_id, n]));
+  assert.deepEqual(out.edges, [{ from: '1', to: '2', count: 9 }, { from: '1', to: '3', count: 1 }, { from: '3', to: '2', count: 2 }]);
+  assert.equal(by['1'].depends_on, 2, 'goal 1 waits on two goals, though ten task edges carry it');
+  assert.equal(by['2'].depended_on_by, 2);
+  assert.equal(by['2'].depends_on, 0);
+});
+
+await test('counts split connected from isolated, and the two add up to the goals', () => {
+  const out = shapeGraph({ goals: [g(1), g(2), g(3), g(4)], edges: [e(1, 2)] });
+  assert.deepEqual(out.counts, { goals: 4, connected: 2, isolated: 2, edges: 1 });
+});
+
+await test('an edge to a goal that is not a node is dropped, not drawn to nowhere; self and duplicate edges too', () => {
+  const out = shapeGraph({ goals: [g(1), g(2)], edges: [e(1, 99), e(2, 2), e(1, 2, 3), e(1, 2, 3)] });
+  assert.deepEqual(out.edges, [{ from: '1', to: '2', count: 3 }]);
+});
+
+await test('a category is attached as {id, slug, label}; an uncategorised goal carries null (legal, ADR 0192)', () => {
+  const out = shapeGraph({ goals: [g(1, { category_id: 7 }), g(2)], edges: [] }, CATS);
+  assert.deepEqual(out.nodes[0].category, { id: '7', slug: 'security', label: 'Security' });
+  assert.equal(out.nodes[1].category, null);
+});
+
+await test('a PRIVATE goal the viewer cannot see stays a node (so neighbours are not falsely isolated) but loses title and category', () => {
+  const out = shapeGraph({ goals: [g(1, { visible: false, category_id: 7, title: 'Secret roadmap' }), g(2)], edges: [e(2, 1)] }, CATS);
+  const hidden = out.nodes[0];
+  assert.equal(hidden.title, null);
+  assert.equal(hidden.category, null);
+  assert.equal(hidden.task_total, 4, 'counts are not the secret — the prose is (ADR 0112)');
+  assert.equal(hidden.depended_on_by, 1, 'and its edges still count, or the structure would lie');
+  assert.equal(JSON.stringify(out).includes('Secret roadmap'), false, 'the title is nowhere in the payload');
+});
+
+await test('an empty corpus is a valid, empty graph', () => {
+  assert.deepEqual(shapeGraph({}), { nodes: [], edges: [], counts: { goals: 0, connected: 0, isolated: 0, edges: 0 } });
+});
+
+// ---- the SQL, against a recording pool ----------------------------------------
+
+function fakePool(goalRows = [], edgeRows = []) {
+  const calls = [];
+  return {
+    calls,
+    async query(sql, params) {
+      calls.push({ sql, params });
+      return { rows: /FROM dependencies/.test(sql) ? edgeRows : goalRows };
+    },
+  };
+}
+
+await test('the viewer, the Archon flag and the shared status buckets ride as bind parameters — never interpolated', async () => {
+  const pool = fakePool();
+  await goalGraphRows({ versionId: 'V1', viewerId: 42, viewerIsArchon: true }, { pool });
+  const [goalsQ] = pool.calls;
+  assert.deepEqual(goalsQ.params, ['V1', true, 42, CUT_STATUSES, DONE_STATUSES]);
+  assert.equal(/\b42\b/.test(goalsQ.sql), false, 'no viewer id in the SQL text');
+});
+
+await test('only an explicit archon === true widens visibility (a truthy string is not an Archon)', async () => {
+  const pool = fakePool();
+  await goalGraphRows({ viewerId: 1, viewerIsArchon: 'yes' }, { pool });
+  assert.equal(pool.calls[0].params[1], false);
+});
+
+await test('a repeated ?version= (parsed as an array by the query string) is flattened before it binds — never a driver-level 500', async () => {
+  const pool = fakePool();
+  await goalGraphRows({ versionId: ['V1', 'V2'] }, { pool });
+  assert.equal(pool.calls[0].params[0], 'V1');
+  assert.equal(pool.calls[1].params[0], 'V1');
+});
+
+await test('the edge query keeps only task→task dependencies that CROSS a goal boundary', async () => {
+  const pool = fakePool();
+  await goalGraphRows({}, { pool });
+  const sql = pool.calls[1].sql;
+  assert.match(sql, /d\.from_kind = 'task'/);
+  assert.match(sql, /d\.to_kind\s+= 'task'/);
+  assert.match(sql, /ft\.goal_id <> tt\.goal_id/, 'a dependency inside one goal belongs to the per-goal forest, not this map');
+});
+
+await test('NO TASK IDENTITY leaves either query — nothing selects a task id or a task title', async () => {
+  const pool = fakePool();
+  await goalGraphRows({}, { pool });
+  for (const { sql } of pool.calls) {
+    const select = sql.slice(sql.lastIndexOf('SELECT'), sql.indexOf('FROM', sql.lastIndexOf('SELECT')));
+    assert.equal(/\bt\.(id|title)\b|\b(ft|tt)\.(id|title)\b/.test(select), false, `a task column is selected: ${select}`);
+  }
+});
+
+await test('the payload is the shaped graph, categories included, from one fake read', async () => {
+  const pool = fakePool([{ goal_id: '1', title: 'A', status: 'open', version_id: 'V1', category_id: 7, visible: true, task_total: 3, task_done: 3 },
+    { goal_id: '2', title: 'B', status: 'open', version_id: 'V1', category_id: null, visible: true, task_total: 2, task_done: 0 }],
+  [{ from_goal_id: '2', to_goal_id: '1', count: 5 }]);
+  const out = await goalGraph({ viewerId: 1 }, { pool, categoryIndex: async () => CATS });
+  assert.equal(out.nodes[0].category.label, 'Security');
+  assert.deepEqual(out.edges, [{ from: '2', to: '1', count: 5 }]);
+  assert.equal(out.counts.connected, 2);
+});
+
+// ---- the handler ---------------------------------------------------------------
+
+function run(handler, req) {
+  const res = { body: null, failed: null, json(b) { this.body = b; return this; }, fail(code, o) { this.failed = { code, o }; return this; } };
+  return handler(req, res).then(() => res);
+}
+
+await test('the handler reads identity from the authenticated request, never the query', async () => {
+  let seen = null;
+  const h = goalGraphHandler({ read: async (o) => { seen = o; return { nodes: [], edges: [], counts: {} }; }, log: { error() {} } });
+  const res = await run(h, { builder: { id: 7, rank: 'metic' }, query: { version: 'V2', viewerId: '999', viewerIsArchon: 'true' } });
+  assert.deepEqual(seen, { versionId: 'V2', viewerId: 7, viewerIsArchon: false });
+  assert.ok(res.body);
+});
+
+await test('an Archon request widens visibility; no version means every version', async () => {
+  let seen = null;
+  const h = goalGraphHandler({ read: async (o) => { seen = o; return {}; }, log: { error() {} } });
+  await run(h, { builder: { id: 1, rank: 'archon' }, query: {} });
+  assert.deepEqual(seen, { versionId: null, viewerId: 1, viewerIsArchon: true });
+});
+
+await test('a failed read is a named 500, never a stack trace', async () => {
+  const errors = [];
+  const h = goalGraphHandler({ read: async () => { throw new Error('db down'); }, log: { error: (...a) => errors.push(a) } });
+  const res = await run(h, { builder: { id: 1, rank: 'metic' }, query: {} });
+  assert.equal(res.failed.code, 'graph_failed');
+  assert.equal(res.failed.o.status, 500);
+  assert.equal(errors.length, 1);
+});
+
+// ---- mounting --------------------------------------------------------------------
+
+await test('/goals/graph is mounted for any signed-in builder, BEFORE /goals/:id (or Express reads "graph" as an id)', () => {
+  const graphAt = GOALS_ROUTE.indexOf("router.get('/goals/graph'");
+  const idAt = GOALS_ROUTE.indexOf("router.get('/goals/:id'");
+  assert.ok(graphAt > -1, 'the route is registered');
+  assert.ok(graphAt < idAt, 'literal before param');
+  assert.match(GOALS_ROUTE.slice(graphAt, graphAt + 120), /auth\.requireBuilder/);
+  assert.match(GOALS_ROUTE.slice(Math.max(0, graphAt - 200), graphAt), /rank: any-builder/, 'the route-rank scanner needs its declaration');
+});
+
+await test('the module never branches on a category — it is a label here (ADR 0192)', () => {
+  const code = GRAPH_SRC.replace(/^\s*\/\/.*$/gm, '');
+  assert.equal(/\bif\s*\([^)]*category/i.test(code), false);
+  // Each WHERE runs to the next GROUP BY / ORDER BY / closing CTE paren — a
+  // category may be SELECTed for the label, and must never appear in a filter.
+  const wheres = code.split(/\bWHERE\b/).slice(1).map((s) => s.split(/GROUP BY|ORDER BY|\n\s*\)/)[0]);
+  assert.ok(wheres.length >= 2, 'sanity: the queries have WHERE clauses to check');
+  for (const w of wheres) assert.equal(/category/i.test(w), false, `a query filters on category: ${w}`);
+});
+
+summary();

package/tests/goal_map_lib.mjs

@@ -0,0 +1,214 @@
+// tests/goal_map_lib.mjs — the goal map's model and layout, EXECUTED (task
+// 1003479, goal 1000089, ADR 0227 §6 item 3 + the §10.4 amendment).
+//
+// goal-map-lib.js is pure, so this runs the real code over the real harness
+// fixture and over a synthetic corpus built to the SHAPE the ADR measured on the
+// live database (70 goals, 34 of them with no edge, the rest in one large cluster
+// and a scatter of small ones). What is pinned is what a reader would otherwise
+// have to trust the picture about: that no goal is drawn twice or on top of
+// another, that a goal always sits to the right of what it waits on, that the
+// stand-alone goals never reach the canvas, that the same data always gives the
+// same picture, and that every fact the picture carries is also a table cell.
+//
+// Run:  node tests/goal_map_lib.mjs
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const LIB_PATH = path.join(ROOT, 'modules/hall-ui/public/goal-map-lib.js');
+const L = require(LIB_PATH);
+const FIXTURE = JSON.parse(fs.readFileSync(path.join(ROOT, 'scripts/hall-preview/fixtures/goals__graph.json'), 'utf8'));
+
+const { test, summary } = makeRunner();
+
+const node = (id, extra = {}) => ({ goal_id: String(id), title: `Goal ${id}`, status: 'open', version_id: 'V1', category: null, task_total: 5, task_done: 2, ...extra });
+const edge = (from, to, count = 1) => ({ from: String(from), to: String(to), count });
+
+function overlaps(a, b) {
+  return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+}
+function assertSound(a, lay, label) {
+  const ids = lay.nodes.map((n) => n.id);
+  assert.equal(new Set(ids).size, ids.length, `${label}: no goal is drawn twice`);
+  assert.equal(ids.length, a.connected, `${label}: exactly the connected goals are drawn`);
+  for (let i = 0; i < lay.nodes.length; i++) {
+    for (let j = i + 1; j < lay.nodes.length; j++) {
+      assert.equal(overlaps(lay.nodes[i], lay.nodes[j]), false, `${label}: ${lay.nodes[i].id} overlaps ${lay.nodes[j].id}`);
+    }
+  }
+  for (const n of lay.nodes) {
+    assert.ok(n.x >= 0 && n.y >= 0, `${label}: ${n.id} is on the canvas`);
+    assert.ok(n.x + n.w <= lay.width && n.y + n.h <= lay.height, `${label}: ${n.id} fits inside the svg's own size`);
+  }
+}
+
+// A deterministic synthetic corpus with the measured shape: `clusterSizes` goals
+// wired into connected clusters (each a chain plus a few extra edges) and `alone`
+// goals with no edge. A tiny LCG, so the test is the same on every machine.
+function synth(clusterSizes, alone) {
+  let seed = 20260919;
+  const rnd = () => { seed = (seed * 1664525 + 1013904223) % 4294967296; return seed / 4294967296; };
+  const nodes = []; const edges = []; let id = 1000;
+  for (const size of clusterSizes) {
+    const ids = [];
+    for (let i = 0; i < size; i++) { ids.push(++id); nodes.push(node(id, { category: rnd() < 0.5 ? { id: '1', slug: 'security', label: 'Security' } : null })); }
+    for (let i = 1; i < size; i++) edges.push(edge(ids[i], ids[Math.floor(rnd() * i)], 1 + Math.floor(rnd() * 4)));
+    for (let k = 0; k < Math.floor(size / 3); k++) {
+      const a = ids[Math.floor(rnd() * size)]; const b = ids[Math.floor(rnd() * size)];
+      if (a !== b && !edges.some((e) => e.from === String(a) && e.to === String(b))) edges.push(edge(a, b));
+    }
+  }
+  for (let i = 0; i < alone; i++) nodes.push(node(++id));
+  return { nodes, edges };
+}
+
+// ---- structure -----------------------------------------------------------------
+
+await test('the goals split into connected and stand-alone, and the two add up', () => {
+  const a = L.analyse({ nodes: [node(1), node(2), node(3), node(4)], edges: [edge(1, 2)] });
+  assert.equal(a.connected, 2);
+  assert.deepEqual(a.isolated, ['3', '4']);
+  assert.equal(a.connected + a.isolated.length, a.order.length);
+});
+
+await test('clusters are found, largest first, and every connected goal knows its cluster', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4, 5, 6, 7].map((i) => node(i)), edges: [edge(1, 2), edge(3, 4), edge(4, 5), edge(5, 6)] });
+  assert.deepEqual(a.clusters.map((c) => c.length), [4, 2]);
+  assert.equal(a.clusterOf['3'].index, 1);
+  assert.equal(a.clusterOf['3'].size, 4);
+  assert.equal(a.clusterOf['1'].index, 2);
+  assert.equal(a.clusterOf['7'], undefined, 'a stand-alone goal belongs to no cluster');
+});
+
+await test('an edge to an unknown goal, a self edge and a duplicate are ignored, not drawn to nowhere', () => {
+  const a = L.analyse({ nodes: [node(1), node(2)], edges: [edge(1, 99), edge(2, 2), edge(1, 2, 3), edge(1, 2, 3)] });
+  assert.equal(a.edges.length, 1);
+});
+
+// ---- layout --------------------------------------------------------------------
+
+await test('a goal sits to the RIGHT of every goal it waits on (dependencies read left to right)', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4].map((i) => node(i)), edges: [edge(2, 1), edge(3, 2), edge(4, 2)] });
+  const lay = L.layout(a);
+  const x = Object.fromEntries(lay.nodes.map((n) => [n.id, n.x]));
+  for (const e of a.edges) assert.ok(x[e.to] < x[e.from], `${e.from} waits on ${e.to}, so must be right of it`);
+});
+
+await test('stand-alone goals are never drawn — they are a list, not dots on an empty canvas', () => {
+  const a = L.analyse({ nodes: [node(1), node(2), node(3)], edges: [edge(1, 2)] });
+  const lay = L.layout(a);
+  assert.deepEqual(lay.nodes.map((n) => n.id).sort(), ['1', '2']);
+});
+
+await test('a loop (two goals each waiting on the other) terminates and places both', () => {
+  const a = L.analyse({ nodes: [node(1), node(2), node(3)], edges: [edge(1, 2), edge(2, 1), edge(3, 1)] });
+  const lay = L.layout(a);
+  assert.equal(lay.nodes.length, 3);
+  assertSound(a, lay, 'loop');
+});
+
+await test('the same data always gives the same picture (no random seed, no drift between visits)', () => {
+  const p = synth([9, 4, 3], 6);
+  assert.deepEqual(L.layout(L.analyse(p)), L.layout(L.analyse(p)));
+});
+
+await test('every edge path starts at its dependency and ends at its dependent', () => {
+  const a = L.analyse({ nodes: [node(1), node(2)], edges: [edge(2, 1, 4)] });
+  const lay = L.layout(a);
+  const by = Object.fromEntries(lay.nodes.map((n) => [n.id, n]));
+  const [e] = lay.edges;
+  assert.ok(e.d.startsWith(`M${by['1'].x + lay.nodeW} ${by['1'].y + lay.nodeH / 2}`), 'leaves the dependency’s right edge');
+  assert.ok(e.d.endsWith(`${by['2'].x} ${by['2'].y + lay.nodeH / 2}`), 'arrives at the dependent’s left edge');
+  assert.ok(e.width >= 1 && e.width <= 3);
+});
+
+await test('the harness fixture lays out soundly — one large cluster, pairs, a loop and a private goal', () => {
+  const a = L.analyse(FIXTURE);
+  const lay = L.layout(a);
+  assertSound(a, lay, 'fixture');
+  assert.ok(a.clusters.length >= 4 && a.clusters[0].length > a.clusters[1].length, 'reads as one cluster and a scatter');
+  assert.ok(a.isolated.length > 0);
+});
+
+await test('THE SCALE CHECK: the measured shape (70 goals, 34 alone, one big cluster) lays out soundly and fast', () => {
+  const p = synth([17, 6, 4, 3, 2, 2, 2], 34); // 36 connected + 34 alone = the measured 70
+  assert.equal(p.nodes.length, 70);
+  const a = L.analyse(p);
+  assert.equal(a.isolated.length, 34);
+  const t0 = Date.now();
+  const lay = L.layout(a);
+  const ms = Date.now() - t0;
+  assertSound(a, lay, 'scale');
+  assert.ok(ms < 500, `laid out in ${ms}ms`);
+  // The page scrolls the svg INSIDE its own box, so a wide picture is fine — but
+  // it must not be absurd: the largest cluster is a handful of columns, not a line.
+  assert.ok(lay.width < 3200, `width ${lay.width}`);
+});
+
+// ---- categories and the table ---------------------------------------------------
+
+await test('a category keeps its colour by alphabetical order of the labels present, and repeats past eight', () => {
+  const cats = ['Zeta', 'Alpha', 'Mid'].map((label, i) => ({ id: String(i), slug: label.toLowerCase(), label }));
+  const a = L.analyse({ nodes: [node(1, { category: cats[0] }), node(2, { category: cats[1] }), node(3, { category: cats[2] }), node(4)], edges: [] });
+  const c = L.categories(a);
+  assert.deepEqual(c.list.map((x) => x.label), ['Alpha', 'Mid', 'Zeta']);
+  assert.deepEqual(c.list.map((x) => x.colour), [0, 1, 2]);
+  assert.equal(c.uncategorised, 1);
+  assert.equal(L.colourOf(a.byId['4'], c), 'none', 'uncategorised is legal and wears no colour');
+  const many = Array.from({ length: 10 }, (_, i) => ({ id: String(i), slug: `c${String(i).padStart(2, '0')}`, label: `C${String(i).padStart(2, '0')}` }));
+  const big = L.categories(L.analyse({ nodes: many.map((m, i) => node(i + 1, { category: m })), edges: [] }));
+  assert.equal(big.list[8].colour, 0, 'the ninth wraps — the WORD on the node still says which it is');
+});
+
+await test('the table has one row per goal and carries every fact the picture does, both directions by name', () => {
+  const a = L.analyse({ nodes: [node(1, { title: 'Base', task_total: 9, task_done: 4, category: { id: '1', slug: 's', label: 'Security' } }), node(2, { title: 'Top' }), node(3, { title: 'Alone' })], edges: [edge(2, 1, 6)] });
+  const rows = L.tableRows(a);
+  assert.equal(rows.length, 3, 'stand-alone goals are rows too — the table is the whole map');
+  const base = rows.find((r) => r.id === '1');
+  const top = rows.find((r) => r.id === '2');
+  assert.equal(base.category, 'Security');
+  assert.equal(base.done + '/' + base.total, '4/9');
+  assert.deepEqual(top.waits, [{ id: '1', title: 'Base', count: 6 }]);
+  assert.deepEqual(base.needed, [{ id: '2', title: 'Top', count: 6 }]);
+  assert.equal(top.clusterLabel, 'Cluster 1 · 2 goals');
+  assert.equal(rows.find((r) => r.id === '3').clusterLabel, 'Stands alone');
+  assert.equal(rows[rows.length - 1].id, '3', 'stand-alone goals sort last');
+});
+
+await test('a private goal is named as one, in the table and in a neighbour’s dependency list', () => {
+  const a = L.analyse({ nodes: [node(1, { title: null }), node(2)], edges: [edge(2, 1)] });
+  const rows = L.tableRows(a);
+  assert.equal(rows.find((r) => r.id === '1').title, 'A private goal');
+  assert.equal(rows.find((r) => r.id === '1').isPrivate, true);
+  assert.equal(rows.find((r) => r.id === '2').waits[0].title, 'A private goal');
+});
+
+await test('the split is STATED, with the measured numbers only', () => {
+  const a = L.analyse({ nodes: [1, 2, 3, 4, 5].map((i) => node(i)), edges: [edge(1, 2), edge(2, 3)] });
+  const d = L.describe(a);
+  assert.match(d.summary, /5 goals carry work/);
+  assert.match(d.summary, /3 of them are tied to another goal/);
+  assert.match(d.summary, /the other 2 stand alone/);
+  assert.match(d.summary, /form 1 cluster, the largest with 3 goals/);
+});
+
+await test('no edges at all is said plainly and the table is called the whole map (ADR 0227 §3: the right amount of map may be none)', () => {
+  const d = L.describe(L.analyse({ nodes: [node(1), node(2)], edges: [] }));
+  assert.match(d.graph, /no graph to draw — the table below is the whole map/);
+  assert.match(L.describe(L.analyse({ nodes: [], edges: [] })).summary, /No goal carries any work/);
+});
+
+// ---- purity -----------------------------------------------------------------------
+
+await test('the lib is pure and cannot reach a task: no DOM, no fetch, no task input', () => {
+  const src = fs.readFileSync(LIB_PATH, 'utf8').replace(/^\s*\/\/.*$/gm, '');
+  assert.equal(/\bdocument\b|\bfetch\b|\bwindow\b|XMLHttpRequest/.test(src.replace(/root\.OTBGoalMapLib/, '')), false);
+  assert.equal(/task_id|\/tasks\b|\.tasks\b/.test(src), false, 'view A/D need task rows; this file has nowhere to put one (ADR 0227 §7)');
+});
+
+summary();

package/tests/goal_map_page.mjs

@@ -0,0 +1,236 @@
+// tests/goal_map_page.mjs — the goal map page, EXECUTED (task 1003479, goal
+// 1000089; ADR 0227 §5 and §7).
+//
+// The real hall-kit.js, the real goal-map-lib.js and the real goal-map.js run in
+// one vm against a stub DOM and a stubbed GET /goals/graph. What the ADR made
+// non-negotiable is asserted here as behaviour, not read off the source:
+//   - the TABLE is on the page by default (§5.1) — no toggle hides it;
+//   - category is TEXT on every node as well as a colour (§5.3);
+//   - the picture scrolls inside its own box and never widens the page (§5.2);
+//   - there is no control that could reach view A (every task) or view D
+//     (densified) (§7) — the only fetch is the aggregate;
+//   - the stand-alone goals are a list, not dots (§10.4 item 1), and the split is
+//     stated on the page.
+// Plus the one thing the browser adds that a lib test cannot see: a goal title is
+// builder-authored text and must never become markup.
+//
+// Run:  node tests/goal_map_page.mjs
+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';
+import { makeRunner, makeEl, walk } from './helpers.mjs';
+
+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 KIT_JS = read('hall-kit.js');
+const LIB_JS = read('goal-map-lib.js');
+const PAGE_JS = read('goal-map.js');
+const PAGE_HTML = read('goal-map.html');
+const PAGE_CSS = read('goal-map.css');
+const FIXTURE = JSON.parse(fs.readFileSync(path.join(ROOT, 'scripts/hall-preview/fixtures/goals__graph.json'), 'utf8'));
+
+const { test, summary } = makeRunner();
+const tick = () => new Promise((r) => setTimeout(r, 0));
+const settle = async () => { for (let i = 0; i < 20; i++) await tick(); };
+
+const node = (id, extra = {}) => ({ goal_id: String(id), title: `Goal ${id}`, status: 'open', version_id: 'V1', category: null, task_total: 5, task_done: 2, depends_on: 0, depended_on_by: 0, ...extra });
+
+async function boot(payload, { status = 200, fail = false } = {}) {
+  const root = makeEl('div');
+  const reg = (id, hidden = false) => { const el = makeEl('div', { id }); if (hidden) el.hidden = true; root.appendChild(el); return el; };
+  ['gm-sub', 'gm-graph', 'gm-legend', 'gm-alone', 'gm-alone-lede', 'gm-table'].forEach((id) => reg(id));
+  ['gm-alone-scroll', 'gm-table-scroll'].forEach((id) => reg(id, true));
+
+  const documentObj = {
+    getElementById: (id) => walk(root, (el) => (el.id === id ? el : null)),
+    // SVG elements: the stub's own class/id only follow attrs at construction, so
+    // mirror what a browser does when setAttribute writes them.
+    createElementNS(_ns, tag) {
+      const el = makeEl(tag);
+      const orig = el.setAttribute.bind(el);
+      el.setAttribute = (k, v) => { orig(k, v); if (k === 'class') el.className = String(v); if (k === 'id') el.id = String(v); };
+      return el;
+    },
+  };
+  const requests = [];
+  const navigations = [];
+  const locationObj = { hostname: 'builders.example.test', assign: (u) => navigations.push(u) };
+  const windowObj = {
+    OTB: { escapeHtml: (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c])) },
+    localStorage: { getItem: () => null, setItem() {} },
+    location: locationObj,
+    addEventListener() {},
+  };
+  const sandbox = {
+    window: windowObj, self: windowObj, document: documentObj, location: locationObj, console: { error() {}, log() {}, warn() {} },
+    setTimeout, clearTimeout, Promise, Date, Math, JSON, Error, Number, String, Object, Array, Boolean, Set, Map, RegExp, encodeURIComponent,
+    fetch: async (url) => {
+      requests.push(url);
+      if (fail) throw new Error('offline');
+      return { ok: status === 200, status, json: async () => payload };
+    },
+  };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(KIT_JS, sandbox, { filename: 'hall-kit.js' });
+  vm.runInContext(LIB_JS, sandbox, { filename: 'goal-map-lib.js' });
+  vm.runInContext(PAGE_JS, sandbox, { filename: 'goal-map.js' });
+  await settle();
+  const $ = (id) => documentObj.getElementById(id);
+  // The stub matches one compound selector at a time, so `tbody tr` is two steps.
+  const rows = () => { const tb = $('gm-table').querySelector('tbody'); return tb ? tb.querySelectorAll('tr') : []; };
+  return { $, requests, navigations, rows, svg: () => $('gm-graph').querySelector('svg') };
+}
+
+// ---- the table is the page ---------------------------------------------------------
+
+await test('the TABLE is on the page by default — every goal is a row, and nothing hides it behind a toggle', async () => {
+  const h = await boot(FIXTURE);
+  assert.equal(h.$('gm-table-scroll').hidden, false);
+  const rows = h.rows();
+  assert.equal(rows.length, FIXTURE.nodes.length, 'stand-alone goals are rows too');
+  assert.ok(h.$('gm-table').querySelector('table').getAttribute('aria-label'), 'the table is named for a screen reader');
+});
+
+await test('the picture is the enhancement, and it is a role=img figure: no focus stops, no links inside the drawing', async () => {
+  const h = await boot(FIXTURE);
+  const svg = h.svg();
+  assert.ok(svg, 'the map is drawn');
+  assert.equal(svg.getAttribute('role'), 'img');
+  assert.equal(svg.getAttribute('aria-labelledby'), 'gm-cap');
+  assert.equal(svg.querySelectorAll('a').length, 0, 'thirty-six hidden interactive elements from a drawing is the wrong trade');
+  assert.equal(svg.querySelectorAll('[tabindex]').length, 0);
+  assert.match(h.$('gm-graph').querySelector('figcaption').textContent, /also in the table below/);
+});
+
+await test('every goal in the map is a table row too, and every drawn dependency is named in the table', async () => {
+  const h = await boot(FIXTURE);
+  const drawn = h.svg().querySelectorAll('.gm-node').length;
+  assert.equal(drawn, FIXTURE.counts.connected);
+  const tableText = h.$('gm-table').textContent;
+  for (const e of FIXTURE.edges) {
+    const dependent = FIXTURE.nodes.find((n) => n.goal_id === e.from);
+    const dependency = FIXTURE.nodes.find((n) => n.goal_id === e.to);
+    assert.ok(tableText.includes(dependency.title || 'A private goal'), `the table names ${dependency.title}`);
+    assert.ok(tableText.includes(dependent.title || 'A private goal'));
+  }
+});
+
+// ---- category is text, not only colour ------------------------------------------------
+
+await test('CATEGORY IS A WORD on every drawn node, not only a colour — and "No category" is said too', async () => {
+  const h = await boot(FIXTURE);
+  const cats = h.svg().querySelectorAll('.gm-cat').map((t) => t.textContent);
+  assert.equal(cats.length, FIXTURE.counts.connected);
+  assert.ok(cats.every((c) => c.length > 0));
+  assert.ok(cats.includes('No category'), 'an uncategorised goal is legal and named as such (ADR 0192)');
+  assert.ok(cats.some((c) => /Modules|Security|Builders Hall|Economics/.test(c)));
+  assert.ok(h.$('gm-legend').textContent.includes('Modules'), 'and the legend spells each category out');
+});
+
+// ---- the split is stated, the alone goals are a list ----------------------------------
+
+await test('the stand-alone goals are a LIST, never dots, and the split is stated in the page head', async () => {
+  const h = await boot(FIXTURE);
+  const drawnIds = new Set(h.svg().querySelectorAll('.gm-node').map((g) => g.attrs.transform));
+  assert.equal(drawnIds.size, FIXTURE.counts.connected);
+  assert.equal(h.$('gm-alone-scroll').hidden, false);
+  assert.equal(h.$('gm-alone').querySelectorAll('li').length, FIXTURE.counts.isolated);
+  assert.match(h.$('gm-sub').textContent, new RegExp(`the other ${FIXTURE.counts.isolated} stand alone`));
+});
+
+// ---- no view A, no view D -------------------------------------------------------------------
+
+await test('NEITHER VIEW A NOR VIEW D is reachable: one aggregate fetch, and no control on the page that changes what is drawn', async () => {
+  const h = await boot(FIXTURE);
+  assert.deepEqual(h.requests, ['/api/bongos/goals/graph'], 'the only read is the aggregate — it carries no task identity');
+  const controls = /<(?:button|select|input|textarea)\b/i;
+  assert.equal(controls.test(PAGE_HTML), false, 'the page markup has no control at all');
+  assert.equal(h.$('gm-graph').querySelectorAll('button, select, input').length, 0);
+  assert.equal(/include=|\/tasks|task_id|densif/i.test(PAGE_JS.replace(/^\s*\/\/.*$/gm, '').replace(/\/\*[\s\S]*?\*\//g, '')), false,
+    'no path in the page script can ask for a task');
+});
+
+// ---- scrolling ----------------------------------------------------------------------------
+
+await test('the picture scrolls INSIDE its own region and names both overflow axes (the page never scrolls sideways)', async () => {
+  const h = await boot(FIXTURE);
+  const region = h.$('gm-graph').querySelector('.gm-scroll');
+  assert.ok(region && region.contains(h.svg()));
+  assert.equal(region.getAttribute('tabindex'), '0', 'a keyboard reader can scroll it');
+  assert.equal(region.getAttribute('role'), 'region');
+  const rule = PAGE_CSS.match(/\.gm-scroll\s*\{[^}]*\}/)[0];
+  assert.match(rule, /overflow-x:\s*auto/);
+  assert.match(rule, /overflow-y:\s*hidden/, 'one axis named alone makes the other auto (task 1004130)');
+  assert.match(rule, /max-width:\s*100%/);
+});
+
+// ---- text is never markup -------------------------------------------------------------------
+
+await test('a goal title is builder-authored text: it never becomes markup, in the picture or the table or the chips', async () => {
+  const evil = '<img src=x onerror=alert(1)>';
+  const h = await boot({
+    nodes: [node(1, { title: evil, depends_on: 1 }), node(2, { depended_on_by: 1 }), node(3, { title: evil })],
+    edges: [{ from: '1', to: '2', count: 1 }],
+    counts: {},
+  });
+  assert.equal(h.svg().querySelectorAll('img').length, 0);
+  assert.ok(h.svg().querySelectorAll('.gm-name').some((t) => t.textContent.includes('<img')), 'as literal text in the drawing');
+  assert.equal(h.$('gm-table').querySelectorAll('img').length, 0);
+  assert.equal(h.$('gm-alone').querySelectorAll('img').length, 0);
+  assert.ok(h.$('gm-table').textContent.includes(evil), 'shown as the characters the author typed');
+});
+
+// ---- honest states ----------------------------------------------------------------------------
+
+await test('a private goal the viewer cannot read is named as one and is not a link', async () => {
+  const h = await boot({ nodes: [node(1, { title: null, depended_on_by: 1 }), node(2, { depends_on: 1 })], edges: [{ from: '2', to: '1', count: 2 }], counts: {} });
+  const row = h.rows().find((r) => r.textContent.includes('A private goal'));
+  assert.ok(row, 'the row exists');
+  assert.equal(row.querySelectorAll('a').length, 0, 'nothing to open');
+});
+
+await test('no dependency at all says so plainly, draws no picture, and the table is still the whole map', async () => {
+  const h = await boot({ nodes: [node(1), node(2)], edges: [], counts: {} });
+  assert.equal(h.svg(), null);
+  assert.match(h.$('gm-graph').textContent, /no graph to draw — the table below is the whole map/);
+  assert.equal(h.rows().length, 2);
+  assert.equal(h.$('gm-alone-scroll').hidden, true, 'nothing to split when nothing is connected');
+});
+
+await test('an empty corpus renders the empty state and no table', async () => {
+  const h = await boot({ nodes: [], edges: [], counts: {} });
+  assert.match(h.$('gm-graph').textContent, /No goal carries any work yet/);
+  assert.equal(h.$('gm-table-scroll').hidden, true);
+});
+
+await test('a failed read is one honest line — not a blank page, not a stack', async () => {
+  const h = await boot(null, { fail: true });
+  assert.match(h.$('gm-sub').textContent, /Couldn.t load the goal map/);
+  assert.equal(h.svg(), null);
+  assert.equal(h.$('gm-table-scroll').hidden, true);
+});
+
+await test('signed out (401) goes to sign-in like every other hall read', async () => {
+  const h = await boot(null, { status: 401 });
+  assert.deepEqual(h.navigations, ['/api/bongos/auth/web/start']);
+});
+
+// ---- the shell ---------------------------------------------------------------------------------
+
+await test('the page has its h1 in static markup (so every state has one) and loads the lib before the page script', () => {
+  assert.match(PAGE_HTML, /<h1 class="page-head__h">Goal map<\/h1>/);
+  assert.ok(PAGE_HTML.indexOf('goal-map-lib.js') > -1 && PAGE_HTML.indexOf('goal-map-lib.js') < PAGE_HTML.indexOf('goal-map.js'));
+  assert.ok(PAGE_HTML.indexOf('hall-kit.js') < PAGE_HTML.indexOf('goal-map.js'));
+});
+
+await test('it takes NO nav slot (the sky’s rule) — the Goals page is its door', () => {
+  const shell = read('shell.js');
+  assert.equal(/goal-map/.test(shell), false, 'no nav item');
+  assert.match(read('goals.html'), /href="\/builders\/goal-map"/);
+});
+
+summary();

package/tests/hall_page_gate_map.mjs

@@ -48,6 +48,9 @@ const ORACLE = {
   '/builders/atlas': 'requireBuilderPage',
   '/builders/modules': 'requireBuilderPage',
   '/builders/goals': 'requireBuilderPage',
+  // task 1003479: the goal map. GET /goals/graph is requireBuilder like the goal board it
+  // maps, so the page sits on the same tier — and takes no nav slot (the sky's rule).
+  '/builders/goal-map': 'requireBuilderPage',
   '/builders/roadmap': 'requireBuilderPage',
   // Gated at this tier all along, but with no row until task 1003448 walked the
   // module's pages: copy-desk (task 1003113) and ideas (task 1002928) are open to