@bongos/core 1.21.174 → 1.21.176

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

@@ -1,899 +0,0 @@
-#!/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;
-}
-
-// depIdsOf — the dependency ids on one row of a real dump, whatever the API called
-// them. This is load-bearing and was WRONG until task 1003477: `GET /tasks?include=deps`
-// answers with `blocked_by` (an array of {id,title,status,goal_id,satisfied} — see
-// db.attachTaskDepSummaries), and this loader only ever looked for `dependencies`/`deps`.
-// A real dump therefore parsed as a corpus with ZERO edges, and every --from number
-// would have described an empty graph while looking perfectly plausible — the exact
-// failure a spike must not have, because nothing about the output says "no edges here
-// because the field was misnamed". All three spellings are accepted now, and each may
-// hold bare ids or objects carrying one.
-function depIdsOf(row) {
-  // First NON-EMPTY array wins, not the first field present: a dump carrying both an
-  // empty `blocked_by` and a populated `dependencies` would otherwise read as edgeless,
-  // which is the same silent zero this function was written to stop.
-  const raw = [row.blocked_by, row.dependencies, row.deps]
-    .find((v) => Array.isArray(v) && v.length > 0) || [];
-  return raw
-    .map((d) => Number(d && typeof d === 'object' ? d.id : d))
-    .filter(Number.isFinite);
-}
-
-// 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.
-//
-// GOALS: a task with no goal does NOT share a bucket with the other ungoaled tasks —
-// "no goal" is not a goal they have in common, and pooling them would silently turn
-// every dependency between two ungoaled tasks into a WITHIN-goal edge, understating
-// the one number this loader exists to produce. Each gets its own bucket instead;
-// `goalId: null` marks them so census() can report them apart from real goals.
-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();
-  let nextBucket = 0;
-  return rows.map((r) => {
-    const gid = r.goal_id == null || r.goal_id === '' ? null : String(r.goal_id);
-    let bucket;
-    if (gid === null) {
-      bucket = nextBucket++;                      // ungoaled: a bucket of one
-    } else {
-      if (!goalIndex.has(gid)) goalIndex.set(gid, nextBucket++);
-      bucket = goalIndex.get(gid);
-    }
-    return {
-      id: Number(r.id),
-      goal: bucket,
-      goalId: gid,
-      deps: depIdsOf(r),
-    };
-  });
-}
-
-// census — THE TWO NUMBERS task 1003477 exists to measure, plus the three that decide
-// what they mean. ADR 0227 deferred items 3 (the goal graph) and 4 (the dependency
-// forest) on a SYNTHETIC density sweep and said the live corpus must settle them.
-//
-//   with_dependency_pct — the share of tasks carrying at least one dependency row.
-//                         Item 4's question: is there a forest, or is the corpus
-//                         confetti? Note this is OUT-degree (what a task waits on),
-//                         not the degree-0 count the table's `isol%` reports — a task
-//                         that only BLOCKS others declares no row of its own but is
-//                         still drawn, so the two numbers differ and mean different
-//                         things.
-//   cross_goal_pct      — the share of dependency edges whose two ends sit in
-//                         different goals. Item 3's question: does the goal graph
-//                         have EDGES, or is it forty disconnected dots?
-//
-// And what turns those into a verdict: how many goals are left with no cross-goal edge
-// at all (isolated dots a node-link layout has nothing to say about), how many separate
-// components the forest breaks into, and how big the typical one is — a forest of 128
-// four-node trees is a drill-down, not a map, however many edges it contains.
-function census(tasks) {
-  const byId = new Map(tasks.map((t) => [t.id, t]));
-  const edges = [];
-  let withDep = 0;
-  for (const t of tasks) {
-    const live = t.deps.filter((d) => byId.has(d));
-    if (t.deps.length > 0) withDep += 1;
-    for (const d of live) edges.push([t.id, d]);
-  }
-
-  let crossGoal = 0;
-  let touchingUngoaled = 0;
-  const goalPairs = new Set();
-  const goalsWithEdge = new Set();
-  for (const [a, b] of edges) {
-    const ga = byId.get(a).goalId;
-    const gb = byId.get(b).goalId;
-    if (ga === null || gb === null) { touchingUngoaled += 1; continue; }
-    if (ga === gb) continue;
-    crossGoal += 1;
-    goalPairs.add(`${ga}>${gb}`);
-    goalsWithEdge.add(ga);
-    goalsWithEdge.add(gb);
-  }
-
-  const realGoals = new Set(tasks.map((t) => t.goalId).filter((g) => g !== null));
-  const ungoaled = tasks.filter((t) => t.goalId === null).length;
-
-  // The forest: only the tasks with an edge in either direction, and how it breaks up.
-  const degree = new Map(tasks.map((t) => [t.id, 0]));
-  for (const [a, b] of edges) {
-    degree.set(a, degree.get(a) + 1);
-    degree.set(b, degree.get(b) + 1);
-  }
-  const connected = tasks.filter((t) => degree.get(t.id) > 0).map((t) => t.id);
-  const comp = components(connected, edges);
-  const sizes = componentSizes(connected, edges);
-  const median = sizes.length ? sizes[Math.floor(sizes.length / 2)] : 0;
-
-  // THE DRILL-DOWN, which is the shape item 4 is actually scoped as ("queried when a
-  // goal is opened") — not the whole-corpus forest. Per goal: the tasks with an edge
-  // whose OTHER end sits in the same goal. Its WORST case is the number that decides
-  // the item, because a drill-down has to survive its biggest goal, not its median one.
-  const perGoal = new Map();
-  for (const [a, b] of edges) {
-    const ga = byId.get(a).goalId;
-    if (ga === null || ga !== byId.get(b).goalId) continue;
-    if (!perGoal.has(ga)) perGoal.set(ga, new Set());
-    perGoal.get(ga).add(a);
-    perGoal.get(ga).add(b);
-  }
-  const perGoalSizes = [...perGoal.values()].map((v) => v.size).sort((x, y) => y - x);
-  const perGoalMax = perGoalSizes[0] || 0;
-  const perGoalMedian = perGoalSizes.length ? perGoalSizes[Math.floor(perGoalSizes.length / 2)] : 0;
-
-  const pct = (n, d) => (d ? Number(((n / d) * 100).toFixed(2)) : 0);
-  return {
-    tasks: tasks.length,
-    edges: edges.length,
-    with_dependency: withDep,
-    with_dependency_pct: pct(withDep, tasks.length),
-    connected: connected.length,
-    connected_pct: pct(connected.length, tasks.length),
-    cross_goal: crossGoal,
-    cross_goal_pct: pct(crossGoal, edges.length),
-    edges_touching_ungoaled: touchingUngoaled,
-    goals: realGoals.size,
-    ungoaled_tasks: ungoaled,
-    goal_pairs: goalPairs.size,
-    goals_with_cross_goal_edge: goalsWithEdge.size,
-    goals_isolated: realGoals.size - goalsWithEdge.size,
-    goals_isolated_pct: pct(realGoals.size - goalsWithEdge.size, realGoals.size),
-    forest_components: comp.count,
-    forest_largest: comp.largest,
-    forest_median_component: median,
-    per_goal_forests: perGoalSizes.length,
-    per_goal_largest: perGoalMax,
-    per_goal_median: perGoalMedian,
-    // The drill-down clears the bar only if its BIGGEST goal still fits labels.
-    per_goal_largest_labels: inkBudget(perGoalMax || 1).fits_with_label,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// 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".
-// componentSizes — the same union-find, returning the raw sizes largest-first. Split
-// out because "how many components" and "how big is the typical one" are different
-// questions: 128 components says a view is fragmented, but only the MEDIAN size says
-// whether each fragment is a readable little tree or a hairball of its own (census()).
-function componentSizes(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);
-  }
-  return [...sizes.values()].sort((a, b) => b - a);
-}
-
-function components(nodes, edges) {
-  const all = componentSizes(nodes, edges);
-  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,
-  };
-}
-
-// printCensus — the two gating numbers first and in words, because a reader who
-// stops after the first screen must still leave with the answer ADR 0227 asked for.
-function printCensus(c) {
-  const cg = c.goals_with_cross_goal_edge;
-  console.log('live corpus census — the numbers ADR 0227 items 3 and 4 wait on');
-  console.log(`  corpus                     ${c.tasks} tasks, ${c.goals} goals`
-    + (c.ungoaled_tasks ? `, ${c.ungoaled_tasks} task(s) with no goal` : ''));
-  console.log(`  Q1 tasks with a dependency ${c.with_dependency} (${c.with_dependency_pct}%)  → item 4, the dependency forest`);
-  console.log(`  Q2 cross-goal edges        ${c.cross_goal} of ${c.edges} (${c.cross_goal_pct}%)  → item 3, the goal graph`);
-  if (c.edges_touching_ungoaled) {
-    console.log(`     (${c.edges_touching_ungoaled} edge(s) touch a task with no goal and are counted as neither)`);
-  }
-  console.log(`  goal graph shape           ${c.goal_pairs} distinct goal pairs; ${cg} goal(s) carry an edge, `
-    + `${c.goals_isolated} isolated (${c.goals_isolated_pct}%)`);
-  console.log(`  forest shape               ${c.connected} tasks with any edge (${c.connected_pct}%) in `
-    + `${c.forest_components} components; largest ${c.forest_largest}, median ${c.forest_median_component}`);
-  console.log(`  per-goal drill-down        ${c.per_goal_forests} goal(s) have one; largest ${c.per_goal_largest}, `
-    + `median ${c.per_goal_median} — worst case ${c.per_goal_largest_labels ? 'still carries labels' : 'CANNOT carry labels'}`);
-  console.log('');
-}
-
-function main() {
-  const results = [];
-  let realCensus = null;
-
-  if (FROM) {
-    const tasks = loadReal(path.resolve(REPO_ROOT, FROM));
-    realCensus = census(tasks);
-    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, census: realCensus, results }, null, 2)}\n`);
-    return;
-  }
-
-  const pad = (s, n) => String(s).padEnd(n);
-  const rpad = (s, n) => String(s).padStart(n);
-  if (realCensus) printCensus(realCensus);
-  console.log(`task-network-map spike — ${realCensus ? realCensus.tasks : N_TASKS} tasks over ${realCensus ? realCensus.goals : 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, loadReal, depIdsOf, census, viewsOf, components, componentSizes,
-  layout, crossingCount, inkBudget, mulberry32,
-  crc32, chunk, writePng, canvas, goalColor, render,
-};