@bongos/core 1.19.945 → 1.19.947

package/src/bongos/module-scope-map.js

@@ -145,6 +145,16 @@ const MODULE_GLOBS = {
     'modules/ideas/',
     'scripts/gds/capture.js', 'scripts/gds/triage.js', 'scripts/gds/render-ideas.js',
   ],
+  // Role sub-specialities (task 1003855, ADR 0296). Carved into modules/specialities/
+  // but never given a key here, so every file it owns — module.json, db.js, routes,
+  // its two migrations — resolved to NO module territory: a goal scoped to
+  // `specialities` was denied out_of_scope for touching the module it is named after
+  // (found by task 1004132). Every OTHER on-disk module owns its own directory; this
+  // was the only one that did not, and checkEveryModuleDirIsScoped in
+  // scripts/gds/scope-map-guard.js now fails CI if a new carve repeats it.
+  specialities: [
+    'modules/specialities/',
+  ],
   // --- builder prefs (wandering/skill/sound/render) + builder-needs ---
   // Carved into modules/builder-settings/ (BV1.R80 / ADR 0093 §1): the five pref
   // libs + builder-needs + their db slice + the `/me/*-prefs` routes + the
@@ -521,6 +531,62 @@ const SHARED_GLOBS = Object.freeze(
   SHARED_GLOBS_RAW.filter((g) => !touchesOverlap([g], PROTECTED_GLOBS)),
 );
 
+// ── Roots no module glob touches, and why (task 1004132) ────────────────────────
+//
+// This is the RECORDED DECISION behind "the core is owned by nobody", not a note
+// about it. `checkNoNewUnownedRoot` in scripts/gds/scope-map-guard.js reads this
+// map and fails CI BOTH ways: a tracked root that appears here-less is new unowned
+// territory, and an entry whose root became owned (or stopped existing) is stale.
+//
+// WHY THESE ARE ALLOWED TO BE UNOWNED. Per ADR 0086 a goal grants authority
+// BOUNDED to module territory, and `POST /tasks` stays Archon-only for ungoverned
+// creation. So a path with no module owner is not homeless — it is reachable only
+// through the Archon door, which is the safety model, not a gap in it. What must
+// not happen is that set GROWING silently, which is what this freezes.
+//
+// SHRINK-ONLY, like the fitness ratchets. ADR 0086 §4 expects the map to
+// "auto-tighten as ADR 0083 moves code into modules/<key>/" — so an entry leaving
+// this list is the system working. Adding one needs a stated reason, here, in the
+// same commit that adds the root.
+//
+// A `review` reason is an HONEST placeholder, not an endorsement: it marks a root
+// that probably does have a natural owner but whose assignment is its own decision.
+// Assigning nineteen roots in one pass is the one-at-a-time churn task 1004132 was
+// filed to avoid; freezing the set and naming the arguable ones is the cheap half.
+const UNOWNED_ROOTS = Object.freeze({
+  // Generated packaging manifests — written by package-core.js, never hand-edited.
+  '.bongos-core.json': 'generated package manifest (scripts/gds/package-core.js)',
+  '.cloudbongos-core.json': 'generated package manifest (scripts/gds/package-core.js)',
+  // Container build + repo-level dotfiles. review: devsecops already owns the
+  // neighbouring .npmrc / .gitattributes / package.json, so these plausibly belong
+  // to it — but that is a scope-wall change and wants its own decision.
+  '.dockerignore': 'review: container build, plausibly devsecops',
+  'Dockerfile': 'review: container build, plausibly devsecops',
+  'docker-compose.yml': 'review: container build, plausibly devsecops',
+  'docker-entrypoint.sh': 'review: container build, plausibly devsecops',
+  '.gitignore': 'review: repo-level dotfile, plausibly devsecops',
+  '.env.local.example': 'review: repo-level dotfile, plausibly devsecops',
+  // Design tooling checked into the tree. review: plausibly ui-design.
+  '.impeccable/': 'review: design tooling, plausibly ui-design',
+  // Governance + legal. Deliberately not methodology: methodology owns docs/, and
+  // these are the project's constitutional documents rather than its handbook.
+  'LICENSE': 'project legal text',
+  'CODE_OF_CONDUCT.md': 'project governance text',
+  'CONTRIBUTING.md': 'project governance text',
+  'GOVERNANCE.md': 'project governance text',
+  // Top-level product/design statements, read by humans before any module matters.
+  'README.md': 'repo front door',
+  'DESIGN.md': 'top-level design statement',
+  'PRODUCT.md': 'top-level product statement',
+  // The core itself. bin/ is the CLI entrypoint and clients/ is the GENERATED API
+  // client (scripts/gds/gen-api-client.js); public-docs/ is the published site.
+  // These are core, and core is Archon territory by ADR 0086 — the primary case
+  // this list exists to record.
+  'bin/': 'core CLI entrypoint — Archon territory (ADR 0086)',
+  'clients/': 'generated API client (scripts/gds/gen-api-client.js)',
+  'public-docs/': 'published docs site — core',
+});
+
 // A CLI ENTRYPOINT — a single executable script under scripts/, e.g.
 // 'scripts/gds/setup.js'. Structural, not a list: it is a path test, so no roster
 // is hand-maintained here and nothing has to be kept in step with PROTECTED_GLOBS.
@@ -676,6 +742,7 @@ function moduleDriftFiles(moduleKey, files) {
 }
 
 module.exports = {
+  UNOWNED_ROOTS,
   MODULE_GLOBS,
   MODULE_SCOPE_MAP,
   SHARED_GLOBS,

package/src/bongos/serve-internal.js

@@ -1163,13 +1163,16 @@ function mountInternalSurfaces(app) {
   // because the page reads the VIEWER's own trail and nobody else's — the id it
   // asks for comes from GET /me, never from the URL, so a rank could protect
   // nothing here that the session does not already.
+  // task 1003479 (goal 1000089): `goal-map` — the map of which goals wait on which,
+  // reached from Goals. It reads GET /goals/graph, which is `requireBuilder`, so a
+  // page gated any lower would show a signed-out visitor an empty shell.
   // task 1004105 (BV2.R26): `sky` — THE SKY, the ambient view over the same
   // trail the room lists — joins that tier for exactly the same reasons. It is
   // the SAME read (GET /inbox/by-builder/:id with the id from GET /me), drawn
   // as a map instead of a table, so a floor above sign-in would protect on one
   // page what it admits on the other.
   const SIGNEDIN_BUILDERS_PAGE_RE =
-    /^\/builders\/(?:work|settings|atlas|modules|goals|roadmap|copy-desk|studio|ideas|thinking|sky|collab|task|idea|primer(?:\.md)?|diagrams)(?:\.html)?\/?$/;
+    /^\/builders\/(?:work|settings|atlas|modules|goals|goal-map|roadmap|copy-desk|studio|ideas|thinking|sky|collab|task|idea|primer(?:\.md)?|diagrams)(?:\.html)?\/?$/;
   // The diagram image assets under /builders/diagrams/ ride the same tier as the
   // page that embeds them.
   const SIGNEDIN_BUILDERS_PREFIX_RE = /^\/builders\/diagrams\//;

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.945'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.947'; // 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/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();