@bongos/core 1.19.468 → 1.19.469

package/scripts/gds/spike-task-map.js

@@ -0,0 +1,730 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/spike-task-map.js — the task-network-map spike (task 1003282, goal
+// 1000072 "Human legibility"): can a node-link map of ~1,357 tasks be READ?
+//
+// WHY A HARNESS AND NOT AN OPINION. The criterion this goal already shipped under
+// (legibility-sort-and-staleness) set the house rule for questions of this shape:
+// "~1,357 tasks on BONGOS-V1 alone. A view that does not survive that number is not
+// a solution" — and tests/goal_sort_staleness.mjs answered it by EXECUTING the board
+// pipeline over a corpus that size rather than asserting about it. A network map is
+// the same question one dimension harder, so it gets the same treatment: build the
+// graph, lay it out for real, draw it for real, and measure what decides whether a
+// person can read it.
+//
+// WHAT IT MEASURES, AND WHY EACH ONE DECIDES SOMETHING.
+//   ink budget      — screen area ÷ nodes, against the smallest node a person can
+//                     pick out (a bare 5px dot) and the smallest that can carry a
+//                     LABEL (~48×14px). This is the one nothing clever escapes: a
+//                     map whose nodes cannot be told apart is not a slow map, it is
+//                     not a map.
+//   isolated nodes  — degree 0. A "network" that is mostly unconnected dots is not
+//                     a hairball, it is confetti — a different failure needing a
+//                     different answer, and the one this corpus is likeliest to hit.
+//   components      — how many separate islands the layout must place. A force
+//                     layout has nothing to say about where unrelated islands go, so
+//                     each one is a free parameter the reader has to ignore.
+//   crossings       — the classic node-link readability metric; counted exactly on
+//                     the drawn coordinates, not estimated.
+//   layout ms       — whether it can be drawn at all inside a browser interaction.
+//   payload bytes   — the number the goals-page rollup was carved for (5,229,455
+//                     bytes for ~1,400 tasks, measured 2026-08-25). A map that
+//                     re-downloads the corpus loses before it draws.
+//
+// THE DENSITY IS SWEPT, NOT GUESSED. How many tasks actually declare a dependency is
+// a fact of the live DB. Rather than assume one number and build a verdict on it,
+// this sweeps the plausible range and reports where each conclusion flips, so the
+// answer holds whatever the real number turns out to be. Point it at the real corpus
+// with `--from` (a `GET /tasks?include=deps` dump) and it measures that instead.
+//
+// No dependencies, no network, no DB: a deterministic PRNG, a grid-accelerated force
+// layout, an exact crossing count and a hand-rolled PNG encoder (node:zlib), so the
+// evidence is a picture anyone can open rather than a table anyone can dispute.
+//
+// Usage:
+//   node scripts/gds/spike-task-map.js [--nodes 1357] [--goals 40] [--out DIR]
+//                                      [--from tasks.json] [--json] [--no-render]
+
+const fs = require('node:fs');
+const path = require('node:path');
+const zlib = require('node:zlib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// ---------------------------------------------------------------------------
+// argv
+// ---------------------------------------------------------------------------
+
+function arg(name, fallback = null) {
+  const i = process.argv.indexOf(name);
+  return i > -1 && process.argv[i + 1] != null ? process.argv[i + 1] : fallback;
+}
+const HAS = (name) => process.argv.includes(name);
+
+const N_TASKS = Number(arg('--nodes', 1357));
+const N_GOALS = Number(arg('--goals', 40));
+const OUT_DIR = path.resolve(REPO_ROOT, arg('--out', 'docs/research/task-network-map'));
+const FROM = arg('--from', null);
+const AS_JSON = HAS('--json');
+const RENDER = !HAS('--no-render');
+
+// The canvas every ink-budget number is quoted against: a laptop viewport with the
+// hall's chrome removed. Quoting against a 4K desktop would flatter the result for a
+// screen most readers do not have.
+const CANVAS_W = 1280;
+const CANVAS_H = 720;
+
+// The smallest marks a person can actually use. A 5px dot with a 2px gap is about the
+// floor for "I can tell these are two things"; a label needs room for ~6 characters of
+// 11px type before it is a smudge. Both are generous to the map, deliberately.
+const MIN_DOT_PX = 5;
+const MIN_DOT_PITCH = MIN_DOT_PX + 2;
+const MIN_LABEL_W = 48;
+const MIN_LABEL_H = 14;
+
+// The dependency densities swept: the share of tasks declaring at least one
+// dependency. 2% is "almost nobody bothers", 40% is "the backlog is a plan".
+const DENSITIES = [0.02, 0.05, 0.10, 0.20, 0.40];
+
+// ---------------------------------------------------------------------------
+// deterministic PRNG — a spike whose numbers move between runs proves nothing
+// ---------------------------------------------------------------------------
+
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function rnd() {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// the corpus
+// ---------------------------------------------------------------------------
+
+// buildSynthetic — a task corpus with the SHAPE the real schema produces: N tasks
+// spread over G goals, and dependency edges that mostly stay inside a goal and always
+// point backwards (the real table has a no-self-dep constraint and the auto-promotion
+// trigger assumes a DAG, so cycles are not a thing this graph can contain).
+// `density` is the share of tasks declaring at least one dependency.
+function buildSynthetic({ nodes, goals, density, seed = 1003282 }) {
+  const rnd = mulberry32(seed);
+  const tasks = [];
+  for (let i = 0; i < nodes; i++) {
+    tasks.push({ id: i + 1, goal: i % goals, deps: [] });
+  }
+  // Within-goal index, so a dependency can prefer a sibling the way a real chain does.
+  const byGoal = new Map();
+  for (const t of tasks) {
+    if (!byGoal.has(t.goal)) byGoal.set(t.goal, []);
+    byGoal.get(t.goal).push(t);
+  }
+  for (const t of tasks) {
+    if (rnd() >= density) continue;
+    // Most dependents declare one; a few declare two or three.
+    const k = rnd() < 0.75 ? 1 : rnd() < 0.85 ? 2 : 3;
+    for (let j = 0; j < k; j++) {
+      // 85% of edges stay inside the goal — a goal IS the unit of related work.
+      const pool = rnd() < 0.85 ? byGoal.get(t.goal) : tasks;
+      const cand = pool[Math.floor(rnd() * pool.length)];
+      if (!cand || cand.id >= t.id) continue;          // backwards only: no cycles
+      if (t.deps.includes(cand.id)) continue;
+      t.deps.push(cand.id);
+    }
+  }
+  return tasks;
+}
+
+// loadReal — the same shape from a real `GET /tasks?include=deps` dump, so the next
+// session with DB access can replace every synthetic number in the verdict with a
+// measured one by re-running with --from.
+function loadReal(file) {
+  const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const rows = Array.isArray(raw) ? raw : (raw.tasks || raw.rows || []);
+  const goalIndex = new Map();
+  return rows.map((r) => {
+    const g = r.goal_id == null ? '__none__' : String(r.goal_id);
+    if (!goalIndex.has(g)) goalIndex.set(g, goalIndex.size);
+    return {
+      id: Number(r.id),
+      goal: goalIndex.get(g),
+      deps: (r.dependencies || r.deps || []).map(Number).filter(Number.isFinite),
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// graph views — the literal ask, and the two shapes it could become
+// ---------------------------------------------------------------------------
+
+// A: every task a node, every declared dependency an edge. The literal reading of
+//    "a network map of 1,300 tasks".
+// B: only the tasks that actually have an edge — the dependency forest. What is left
+//    when the confetti is swept off the literal view.
+// C: one node per goal, edges aggregated between goals. The rollup the goals page
+//    already computes server-side for its counters.
+function byGoalOf(tasks) {
+  const m = new Map();
+  for (const t of tasks) {
+    if (!m.has(t.goal)) m.set(t.goal, []);
+    m.get(t.goal).push(t);
+  }
+  return m;
+}
+
+function viewsOf(tasks) {
+  const byId = new Map(tasks.map((t) => [t.id, t]));
+  const edgesA = [];
+  for (const t of tasks) for (const d of t.deps) if (byId.has(d)) edgesA.push([t.id, d]);
+
+  const degree = new Map(tasks.map((t) => [t.id, 0]));
+  for (const [a, b] of edgesA) {
+    degree.set(a, degree.get(a) + 1);
+    degree.set(b, degree.get(b) + 1);
+  }
+  const connected = tasks.filter((t) => degree.get(t.id) > 0);
+  const keep = new Set(connected.map((t) => t.id));
+  const edgesB = edgesA.filter(([a, b]) => keep.has(a) && keep.has(b));
+
+  const goalNodes = [...new Set(tasks.map((t) => t.goal))].sort((a, b) => a - b);
+  const goalEdge = new Map();
+  for (const [a, b] of edgesA) {
+    const ga = byId.get(a).goal;
+    const gb = byId.get(b).goal;
+    if (ga === gb) continue;                       // a self-loop is not a map feature
+    const key = `${ga}>${gb}`;
+    goalEdge.set(key, (goalEdge.get(key) || 0) + 1);
+  }
+  const edgesC = [...goalEdge.keys()].map((k) => k.split('>').map(Number));
+
+  // D: every task joined to every other task in its goal. Not a straw man — it is
+  //    what "show me the network of tasks" produces once someone notices that the
+  //    dependency view is mostly unconnected dots and reaches for the relation that
+  //    IS dense. Included so the verdict covers the obvious second attempt.
+  const edgesD = [];
+  for (const [, members] of byGoalOf(tasks)) {
+    for (let i = 0; i < members.length; i++) {
+      for (let j = i + 1; j < members.length; j++) edgesD.push([members[i].id, members[j].id]);
+    }
+  }
+
+  return {
+    A: { name: 'every task', nodes: tasks.map((t) => t.id), groups: tasks.map((t) => t.goal), edges: edgesA },
+    D: { name: 'tasks joined by goal', nodes: tasks.map((t) => t.id), groups: tasks.map((t) => t.goal), edges: edgesD },
+    B: { name: 'tasks with a dependency', nodes: connected.map((t) => t.id), groups: connected.map((t) => t.goal), edges: edgesB },
+    C: { name: 'goals', nodes: goalNodes, groups: goalNodes, edges: edgesC },
+    degree,
+  };
+}
+
+// weakly-connected components, ignoring edge direction — a reader does not perceive
+// arrow direction when deciding "are these two blobs the same thing".
+function components(nodes, edges) {
+  const idx = new Map(nodes.map((n, i) => [n, i]));
+  const parent = nodes.map((_, i) => i);
+  const find = (x) => { while (parent[x] !== x) { parent[x] = parent[parent[x]]; x = parent[x]; } return x; };
+  for (const [a, b] of edges) {
+    const ia = idx.get(a); const ib = idx.get(b);
+    if (ia == null || ib == null) continue;
+    const ra = find(ia); const rb = find(ib);
+    if (ra !== rb) parent[ra] = rb;
+  }
+  const sizes = new Map();
+  for (let i = 0; i < nodes.length; i++) {
+    const r = find(i);
+    sizes.set(r, (sizes.get(r) || 0) + 1);
+  }
+  const all = [...sizes.values()].sort((a, b) => b - a);
+  return { count: all.length, largest: all[0] || 0, singletons: all.filter((s) => s === 1).length };
+}
+
+// ---------------------------------------------------------------------------
+// layout — a real force-directed pass, grid-accelerated so N=1,357 is honest
+// ---------------------------------------------------------------------------
+
+// A real Fruchterman-Reingold pass with BARNES-HUT repulsion (quadtree, theta=0.8) —
+// the same O(n log n) approximation d3-force and every production layout uses, so the
+// timings here are the timings a real implementation would get.
+//
+// It has to be Barnes-Hut and not a cheaper neighbour-grid. A grid gives each node only
+// SHORT-range repulsion, so nodes that share no edge and no cell never push apart; at
+// 1,357 mostly-disconnected nodes that produces a cross-shaped smear which is a
+// property of the approximation and not of the data. Measuring readability on a
+// degenerate layout would prove nothing, and would prove it convincingly.
+//
+// A weak gravity toward the centre keeps disconnected components from drifting to
+// infinity (d3-force's forceCenter, for the same reason): with pure repulsion and no
+// frame, N islands have no equilibrium at all.
+function layout(nodes, edges, { w = CANVAS_W, h = CANVAS_H, iters = 300, seed = 7, margin = 6, theta = 0.8, gravity = 0.015 } = {}) {
+  const n = nodes.length;
+  if (n === 0) return { pos: [], idx: new Map(), ms: 0, iters: 0 };
+  const rnd = mulberry32(seed);
+  const idx = new Map(nodes.map((v, i) => [v, i]));
+  const x = new Float64Array(n);
+  const y = new Float64Array(n);
+  for (let i = 0; i < n; i++) {
+    const a = (i / n) * Math.PI * 2;
+    x[i] = w / 2 + Math.cos(a) * (w / 3) * (0.6 + rnd() * 0.4);
+    y[i] = h / 2 + Math.sin(a) * (h / 3) * (0.6 + rnd() * 0.4);
+  }
+  const ea = new Int32Array(edges.length);
+  const eb = new Int32Array(edges.length);
+  let m = 0;
+  for (const [a, b] of edges) {
+    const ia = idx.get(a); const ib = idx.get(b);
+    if (ia == null || ib == null) continue;
+    ea[m] = ia; eb[m] = ib; m++;
+  }
+  const k = Math.sqrt((w * h) / n);          // FR ideal distance
+  const dx = new Float64Array(n);
+  const dy = new Float64Array(n);
+
+  // Flat-array quadtree, rebuilt each iteration. Children are indices into the same
+  // arrays; -1 is empty. Kept flat because a per-node object tree at 300 iterations is
+  // most of the runtime, and the runtime is one of the things being measured.
+  const CAP = 4 * n + 64;
+  const qx = new Float64Array(CAP);          // centre of mass
+  const qy = new Float64Array(CAP);
+  const qm = new Float64Array(CAP);          // mass (node count)
+  const qs = new Float64Array(CAP);          // cell side
+  const qcx = new Float64Array(CAP);         // cell origin
+  const qcy = new Float64Array(CAP);
+  const qkid = new Int32Array(CAP * 4);
+  const qleaf = new Int32Array(CAP);         // node index for a single-point cell, else -1
+  let qn = 0;
+
+  function newCell(cx, cy, size) {
+    const i = qn++;
+    qx[i] = 0; qy[i] = 0; qm[i] = 0; qs[i] = size; qcx[i] = cx; qcy[i] = cy; qleaf[i] = -1;
+    qkid[i * 4] = -1; qkid[i * 4 + 1] = -1; qkid[i * 4 + 2] = -1; qkid[i * 4 + 3] = -1;
+    return i;
+  }
+  function quadrantOf(cell, px, py) {
+    const half = qs[cell] / 2;
+    return (px >= qcx[cell] + half ? 1 : 0) + (py >= qcy[cell] + half ? 2 : 0);
+  }
+  function insert(cell, p, depth) {
+    // Accumulate the running centre of mass on the way down.
+    qx[cell] = (qx[cell] * qm[cell] + x[p]) / (qm[cell] + 1);
+    qy[cell] = (qy[cell] * qm[cell] + y[p]) / (qm[cell] + 1);
+    qm[cell] += 1;
+    if (qm[cell] === 1) { qleaf[cell] = p; return; }
+    // 24 levels is ~16M subdivisions of the root: past that two points are the same
+    // point for drawing purposes and splitting further would never terminate.
+    if (depth > 24 || qn + 4 >= CAP) return;
+    if (qleaf[cell] >= 0) {
+      const old = qleaf[cell];
+      qleaf[cell] = -1;
+      pushDown(cell, old, depth);
+    }
+    pushDown(cell, p, depth);
+  }
+  function pushDown(cell, p, depth) {
+    const q = quadrantOf(cell, x[p], y[p]);
+    let kid = qkid[cell * 4 + q];
+    if (kid < 0) {
+      const half = qs[cell] / 2;
+      kid = newCell(qcx[cell] + (q & 1 ? half : 0), qcy[cell] + (q & 2 ? half : 0), half);
+      qkid[cell * 4 + q] = kid;
+    }
+    insert(kid, p, depth + 1);
+  }
+
+  const stack = new Int32Array(4096);
+  const t0 = process.hrtime.bigint();
+  for (let it = 0; it < iters; it++) {
+    dx.fill(0); dy.fill(0);
+
+    let minX = Infinity; let minY = Infinity; let maxX = -Infinity; let maxY = -Infinity;
+    for (let i = 0; i < n; i++) {
+      if (x[i] < minX) minX = x[i];
+      if (x[i] > maxX) maxX = x[i];
+      if (y[i] < minY) minY = y[i];
+      if (y[i] > maxY) maxY = y[i];
+    }
+    const side = Math.max(1, maxX - minX, maxY - minY) * 1.05;
+    qn = 0;
+    const root = newCell(minX, minY, side);
+    for (let i = 0; i < n; i++) insert(root, i, 0);
+
+    for (let i = 0; i < n; i++) {
+      let sp = 0;
+      stack[sp++] = root;
+      while (sp > 0) {
+        const c = stack[--sp];
+        if (qm[c] === 0) continue;
+        if (qleaf[c] === i && qm[c] === 1) continue;      // never repel from yourself
+        let vx = x[i] - qx[c];
+        let vy = y[i] - qy[c];
+        let d = Math.sqrt(vx * vx + vy * vy);
+        if (d < 1e-6) { vx = (rnd() - 0.5) * 0.01; vy = (rnd() - 0.5) * 0.01; d = 1e-6; }
+        if (qs[c] / d < theta || qleaf[c] >= 0) {
+          const f = (qm[c] * k * k) / d;
+          dx[i] += (vx / d) * f;
+          dy[i] += (vy / d) * f;
+        } else {
+          for (let q = 0; q < 4; q++) {
+            const kid = qkid[c * 4 + q];
+            if (kid >= 0 && sp < stack.length) stack[sp++] = kid;
+          }
+        }
+      }
+    }
+
+    for (let e = 0; e < m; e++) {
+      const i = ea[e]; const j = eb[e];
+      const vx = x[i] - x[j];
+      const vy = y[i] - y[j];
+      const d = Math.max(1e-3, Math.sqrt(vx * vx + vy * vy));
+      const f = (d * d) / k;
+      const fx = (vx / d) * f;
+      const fy = (vy / d) * f;
+      dx[i] -= fx; dy[i] -= fy;
+      dx[j] += fx; dy[j] += fy;
+    }
+
+    // gravity: without it, N disconnected islands have no equilibrium
+    let gx = 0; let gy = 0;
+    for (let i = 0; i < n; i++) { gx += x[i]; gy += y[i]; }
+    gx /= n; gy /= n;
+    for (let i = 0; i < n; i++) {
+      dx[i] -= (x[i] - gx) * gravity * k;
+      dy[i] -= (y[i] - gy) * gravity * k;
+    }
+
+    const temp = (1 - it / iters) * (w / 10);
+    for (let i = 0; i < n; i++) {
+      const d = Math.max(1e-6, Math.hypot(dx[i], dy[i]));
+      x[i] += (dx[i] / d) * Math.min(d, temp);
+      y[i] += (dy[i] / d) * Math.min(d, temp);
+    }
+  }
+  const ms = Number(process.hrtime.bigint() - t0) / 1e6;
+
+  // Fit the result to the frame. FR's ideal distance is derived from area/n, so the
+  // laid-out extent is not the canvas extent; every real implementation normalises at
+  // the end and so does this. It is the last step, never a per-iteration clamp — a
+  // clamp is a wall force the model does not have, and on a sparse graph it pins most
+  // nodes to the border and draws a ring that is an artifact and nothing else.
+  let minX = Infinity; let minY = Infinity; let maxX = -Infinity; let maxY = -Infinity;
+  for (let i = 0; i < n; i++) {
+    if (x[i] < minX) minX = x[i];
+    if (x[i] > maxX) maxX = x[i];
+    if (y[i] < minY) minY = y[i];
+    if (y[i] > maxY) maxY = y[i];
+  }
+  const spanX = Math.max(1e-6, maxX - minX);
+  const spanY = Math.max(1e-6, maxY - minY);
+  const scale = Math.min((w - 2 * margin) / spanX, (h - 2 * margin) / spanY);
+  const offX = (w - spanX * scale) / 2;
+  const offY = (h - spanY * scale) / 2;
+  const pos = Array.from({ length: n }, (_, i) => [
+    offX + (x[i] - minX) * scale,
+    offY + (y[i] - minY) * scale,
+  ]);
+
+  return { pos, idx, ms, iters };
+}
+
+// ---------------------------------------------------------------------------
+// readability metrics over the DRAWN coordinates
+// ---------------------------------------------------------------------------
+
+const seg = (p, q) => ({ x1: p[0], y1: p[1], x2: q[0], y2: q[1] });
+function crosses(a, b) {
+  const d = (px, py, qx, qy, rx, ry) => (qx - px) * (ry - py) - (qy - py) * (rx - px);
+  const d1 = d(a.x1, a.y1, a.x2, a.y2, b.x1, b.y1);
+  const d2 = d(a.x1, a.y1, a.x2, a.y2, b.x2, b.y2);
+  const d3 = d(b.x1, b.y1, b.x2, b.y2, a.x1, a.y1);
+  const d4 = d(b.x1, b.y1, b.x2, b.y2, a.x2, a.y2);
+  return ((d1 > 0) !== (d2 > 0)) && ((d3 > 0) !== (d4 > 0));
+}
+
+// Exact when the edge count is small enough to afford it, sampled (and scaled back up)
+// when it is not — the count is reported with which of the two produced it, because a
+// sampled number that looks exact is the kind of thing a verdict should not rest on.
+function crossingCount(edges, pos, idx, cap = 2500) {
+  const segs = [];
+  for (const [a, b] of edges) {
+    const ia = idx.get(a); const ib = idx.get(b);
+    if (ia == null || ib == null) continue;
+    if (!pos[ia] || !pos[ib]) continue;
+    segs.push(seg(pos[ia], pos[ib]));
+  }
+  const E = segs.length;
+  if (E < 2) return { crossings: 0, exact: true, edges: E };
+  if (E <= cap) {
+    let c = 0;
+    for (let i = 0; i < E; i++) for (let j = i + 1; j < E; j++) if (crosses(segs[i], segs[j])) c++;
+    return { crossings: c, exact: true, edges: E };
+  }
+  const rnd = mulberry32(99);
+  const SAMPLES = 400000;
+  let hit = 0;
+  for (let s = 0; s < SAMPLES; s++) {
+    const i = Math.floor(rnd() * E);
+    let j = Math.floor(rnd() * E);
+    if (i === j) j = (j + 1) % E;
+    if (crosses(segs[i], segs[j])) hit++;
+  }
+  const pairs = (E * (E - 1)) / 2;
+  return { crossings: Math.round((hit / SAMPLES) * pairs), exact: false, edges: E };
+}
+
+// distinguishableMarks — how many separate things a reader can actually SEE, counted
+// on the drawn coordinates: the number of distinct MIN_DOT_PITCH cells any node lands
+// in. This is the metric that makes "is it readable" a number rather than an opinion,
+// and it is the only one that catches OVERPLOTTING — a layout can place 1,357 nodes
+// perfectly and still show forty marks, because a tight cluster of thirty-four dots at
+// this scale IS one dot. A view whose marks are far below its nodes is not drawing the
+// thing it claims to draw.
+function distinguishableMarks(pos) {
+  const cells = new Set();
+  for (const p of pos) {
+    if (!p) continue;
+    cells.add(`${Math.round(p[0] / MIN_DOT_PITCH)},${Math.round(p[1] / MIN_DOT_PITCH)}`);
+  }
+  return cells.size;
+}
+
+// The number nothing clever escapes. Screen area is fixed; nodes are not.
+function inkBudget(nodeCount, w = CANVAS_W, h = CANVAS_H) {
+  const area = w * h;
+  const per = area / Math.max(1, nodeCount);
+  return {
+    nodes: nodeCount,
+    px2_per_node: Math.round(per),
+    pitch_px: Number(Math.sqrt(per).toFixed(1)),         // side of the square each node owns
+    fits_as_dot: Math.sqrt(per) >= MIN_DOT_PITCH,
+    // A label is not an area, it is a WIDTH. Comparing px² against 48×14 says yes at a
+    // 26px pitch, which would be true only if labels tiled with no gaps and no
+    // clustering — neither is a thing a force layout does. The honest test is whether
+    // the cell each node owns is as wide as the label it must carry.
+    fits_with_label: Math.sqrt(per) >= MIN_LABEL_W,
+    labels_that_fit: Math.floor(w / MIN_LABEL_W) * Math.floor(h / MIN_LABEL_H),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// PNG out — no dependency, so the evidence is a picture and not a promise
+// ---------------------------------------------------------------------------
+
+function crc32(buf) {
+  let c;
+  const table = crc32.table || (crc32.table = (() => {
+    const t = new Int32Array(256);
+    for (let n = 0; n < 256; n++) {
+      c = n;
+      for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+      t[n] = c;
+    }
+    return t;
+  })());
+  let crc = -1;
+  for (let i = 0; i < buf.length; i++) crc = (crc >>> 8) ^ table[(crc ^ buf[i]) & 0xff];
+  return (crc ^ -1) >>> 0;
+}
+
+function chunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length, 0);
+  const td = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(td), 0);
+  return Buffer.concat([len, td, crc]);
+}
+
+function writePng(file, w, h, rgba) {
+  const stride = w * 4;
+  const raw = Buffer.alloc((stride + 1) * h);
+  for (let y = 0; y < h; y++) {
+    raw[y * (stride + 1)] = 0;                       // filter: none
+    rgba.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(w, 0); ihdr.writeUInt32BE(h, 4);
+  ihdr[8] = 8; ihdr[9] = 6; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0;
+  const png = Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk('IHDR', ihdr),
+    chunk('IDAT', zlib.deflateSync(raw, { level: 9 })),
+    chunk('IEND', Buffer.alloc(0)),
+  ]);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, png);
+  return png.length;
+}
+
+// A tiny raster canvas: exactly the primitives a node-link diagram needs.
+function canvas(w, h, bg = [255, 255, 255, 255]) {
+  const buf = Buffer.alloc(w * h * 4);
+  for (let i = 0; i < w * h; i++) buf.set(bg, i * 4);
+  const px = (x, y, [r, g, b, a]) => {
+    x |= 0; y |= 0;
+    if (x < 0 || y < 0 || x >= w || y >= h) return;
+    const o = (y * w + x) * 4;
+    const ia = a / 255;
+    buf[o] = buf[o] * (1 - ia) + r * ia;
+    buf[o + 1] = buf[o + 1] * (1 - ia) + g * ia;
+    buf[o + 2] = buf[o + 2] * (1 - ia) + b * ia;
+    buf[o + 3] = 255;
+  };
+  const line = (x1, y1, x2, y2, col) => {
+    const steps = Math.ceil(Math.max(Math.abs(x2 - x1), Math.abs(y2 - y1)));
+    for (let s = 0; s <= steps; s++) {
+      const t = steps === 0 ? 0 : s / steps;
+      px(x1 + (x2 - x1) * t, y1 + (y2 - y1) * t, col);
+    }
+  };
+  const disc = (cx, cy, r, col) => {
+    for (let y = -r; y <= r; y++) for (let x = -r; x <= r; x++) if (x * x + y * y <= r * r) px(cx + x, cy + y, col);
+  };
+  return { buf, px, line, disc };
+}
+
+// One hue per goal, so "is this cluster one goal or four" is answerable by eye —
+// the question a map like this exists to answer.
+function goalColor(g, alpha = 235) {
+  const hue = (g * 137.508) % 360;                   // golden-angle spread
+  const s = 0.62; const l = 0.48;
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const hp = hue / 60;
+  const xx = c * (1 - Math.abs((hp % 2) - 1));
+  let r = 0; let g2 = 0; let b = 0;
+  if (hp < 1) [r, g2, b] = [c, xx, 0];
+  else if (hp < 2) [r, g2, b] = [xx, c, 0];
+  else if (hp < 3) [r, g2, b] = [0, c, xx];
+  else if (hp < 4) [r, g2, b] = [0, xx, c];
+  else if (hp < 5) [r, g2, b] = [xx, 0, c];
+  else [r, g2, b] = [c, 0, xx];
+  const mm = l - c / 2;
+  return [Math.round((r + mm) * 255), Math.round((g2 + mm) * 255), Math.round((b + mm) * 255), alpha];
+}
+
+function render(file, view, laid, { radius = 3 } = {}) {
+  const cv = canvas(CANVAS_W, CANVAS_H, [252, 252, 251, 255]);
+  for (const [a, b] of view.edges) {
+    const ia = laid.idx.get(a); const ib = laid.idx.get(b);
+    if (ia == null || ib == null) continue;
+    const p = laid.pos[ia]; const q = laid.pos[ib];
+    cv.line(p[0], p[1], q[0], q[1], [110, 110, 118, 90]);
+  }
+  view.nodes.forEach((id, i) => {
+    const p = laid.pos[i];
+    if (!p) return;
+    cv.disc(p[0], p[1], radius, goalColor(view.groups[i]));
+  });
+  return writePng(file, CANVAS_W, CANVAS_H, cv.buf);
+}
+
+// ---------------------------------------------------------------------------
+// the run
+// ---------------------------------------------------------------------------
+
+function measure(label, view, { render: doRender, file, radius = 3 } = {}) {
+  // The frame clamp is the node's own radius plus a pixel, so a node pressed against
+  // the wall by an over-full canvas is drawn whole. It still presses — that rim IS the
+  // ink budget made visible — but a clipped disc would look like a rendering bug and
+  // invite the reader to discount the picture.
+  const laid = layout(view.nodes, view.edges, { margin: radius + 2 });
+  const comp = components(view.nodes, view.edges);
+  const cross = crossingCount(view.edges, laid.pos, laid.idx);
+  const ink = inkBudget(view.nodes.length);
+  const marks = distinguishableMarks(laid.pos);
+  const bytes = Buffer.byteLength(JSON.stringify({ nodes: view.nodes, edges: view.edges }));
+  let pngBytes = null;
+  if (doRender && file) pngBytes = render(file, view, laid, { radius });
+  return {
+    label,
+    view: view.name,
+    nodes: view.nodes.length,
+    edges: view.edges.length,
+    components: comp.count,
+    largest_component: comp.largest,
+    isolated: comp.singletons,
+    isolated_pct: view.nodes.length ? Number(((comp.singletons / view.nodes.length) * 100).toFixed(1)) : 0,
+    marks,
+    overplot_pct: view.nodes.length ? Number((100 - (marks / view.nodes.length) * 100).toFixed(1)) : 0,
+    crossings: cross.crossings,
+    crossings_exact: cross.exact,
+    layout_ms: Number(laid.ms.toFixed(0)),
+    graph_bytes: bytes,
+    png_bytes: pngBytes,
+    ink,
+  };
+}
+
+function main() {
+  const results = [];
+
+  if (FROM) {
+    const tasks = loadReal(path.resolve(REPO_ROOT, FROM));
+    const v = viewsOf(tasks);
+    results.push(measure('real', v.A, { render: RENDER, file: path.join(OUT_DIR, 'real-a-every-task.png') }));
+    results.push(measure('real', v.B, { render: RENDER, file: path.join(OUT_DIR, 'real-b-dependency-forest.png') }));
+    results.push(measure('real', v.C, { render: RENDER, file: path.join(OUT_DIR, 'real-c-goals.png'), radius: 8 }));
+    results.push(measure('real', v.D, { render: RENDER, file: path.join(OUT_DIR, 'real-d-joined-by-goal.png') }));
+  } else {
+    for (const density of DENSITIES) {
+      const tasks = buildSynthetic({ nodes: N_TASKS, goals: N_GOALS, density });
+      const v = viewsOf(tasks);
+      const pct = Math.round(density * 100);
+      // Only the two ends of the sweep are drawn — five pairs of near-identical
+      // hairballs is not more evidence, it is more files.
+      const draw = RENDER && (density === DENSITIES[0] || density === DENSITIES[DENSITIES.length - 1]);
+      results.push({ density, ...measure(`p=${pct}%`, v.A, { render: draw, file: path.join(OUT_DIR, `a-every-task-p${pct}.png`) }) });
+      results.push({ density, ...measure(`p=${pct}%`, v.B, { render: draw, file: path.join(OUT_DIR, `b-dependency-forest-p${pct}.png`) }) });
+      results.push({ density, ...measure(`p=${pct}%`, v.C, { render: draw, file: path.join(OUT_DIR, `c-goals-p${pct}.png`), radius: 8 }) });
+      // D does not depend on the dependency density at all — that is its whole point —
+      // so it is measured and drawn once rather than five identical times.
+      if (density === DENSITIES[0]) {
+        results.push({ density: null, ...measure('any', v.D, { render: RENDER, file: path.join(OUT_DIR, 'd-joined-by-goal.png') }) });
+      }
+    }
+  }
+
+  if (AS_JSON) {
+    process.stdout.write(`${JSON.stringify({ canvas: [CANVAS_W, CANVAS_H], nodes: N_TASKS, goals: N_GOALS, results }, null, 2)}\n`);
+    return;
+  }
+
+  const pad = (s, n) => String(s).padEnd(n);
+  const rpad = (s, n) => String(s).padStart(n);
+  console.log(`task-network-map spike — ${N_TASKS} tasks over ${N_GOALS} goals, drawn at ${CANVAS_W}×${CANVAS_H}`);
+  console.log(`ink floor: a legible dot needs ${MIN_DOT_PITCH}px of pitch; a label needs ${MIN_LABEL_W}×${MIN_LABEL_H}px `
+    + `(${inkBudget(1).labels_that_fit} labels fit on this canvas, total)`);
+  console.log('');
+  console.log([pad('density', 9), pad('view', 26), rpad('nodes', 6), rpad('edges', 6), rpad('isol%', 6),
+    rpad('comps', 6), rpad('marks', 6), rpad('lost%', 6), rpad('cross', 9), rpad('pitch', 7),
+    rpad('label?', 7), rpad('ms', 6), rpad('KB', 7)].join(' '));
+  console.log('-'.repeat(120));
+  for (const r of results) {
+    console.log([
+      pad(r.label, 9), pad(r.view, 26), rpad(r.nodes, 6), rpad(r.edges, 6), rpad(r.isolated_pct, 6),
+      rpad(r.components, 6), rpad(r.marks, 6), rpad(r.overplot_pct, 6),
+      rpad(r.crossings + (r.crossings_exact ? '' : '~'), 9),
+      rpad(`${r.ink.pitch_px}px`, 7), rpad(r.ink.fits_with_label ? 'yes' : 'NO', 7),
+      rpad(r.layout_ms, 6), rpad((r.graph_bytes / 1024).toFixed(0), 7),
+    ].join(' '));
+  }
+  console.log('');
+  console.log('marks = distinct 7px cells any node lands in — what a reader can actually tell apart.');
+  console.log('lost% = share of nodes that overplot onto a mark another node already owns.');
+  console.log('');
+  console.log(`PNGs: ${path.relative(REPO_ROOT, OUT_DIR)}/`);
+}
+
+if (require.main === module) main();
+
+// The rasteriser is exported for the same reason the graph maths is: the figures
+// this file writes are cited as EVIDENCE in ADR 0227, so a stride, CRC or
+// alpha-blend bug would quietly corrupt the evidence rather than fail loudly.
+// Exported = coverable; see tests/spike_task_map.mjs.
+module.exports = {
+  buildSynthetic, viewsOf, components, layout, crossingCount, inkBudget, mulberry32,
+  crc32, chunk, writePng, canvas, goalColor, render,
+};