pi-weave 0.1.7 → 0.1.9

package/src/web/shared/graph.ts

@@ -0,0 +1,213 @@
+/**
+ * The graph shapes as they appear **on the wire** (weave-workspace §5.3).
+ *
+ * ## Why these are declared here and not imported from core
+ *
+ * They used to be `import type { GraphModel } from "../../core/graph/model"`,
+ * and that single line was an architectural violation with a build failure
+ * attached to it.
+ *
+ * The reasoning that put it there was: "`import type` erases at compile time,
+ * so it cannot drag `node:fs` into the browser bundle." That is true, and it
+ * is also not the whole story. Type erasure protects the **bundle**; it does
+ * nothing for the **typecheck**. To resolve `GraphModel`, TypeScript must load
+ * `src/core/graph/model.ts`, which imports `../types`, and the compiler walks
+ * that whole graph — under `tsconfig.web.json`, which deliberately has
+ * `"types": []` and no node lib, so every `node:fs` in the transitive closure
+ * is an error. The client tier was importing core in every sense that
+ * mattered except the one the rule was written to check.
+ *
+ * So the tier rule is now literal rather than aspirational: **nothing under
+ * `src/web/shared/` imports `src/core` at all**, not even as a type. That is
+ * stricter than the §2 table as written (which permits core types here), and
+ * it is the version worth having, because "types only" is a distinction the
+ * compiler does not make when resolving a project.
+ *
+ * ## The contract is deliberately a copy, not an alias
+ *
+ * This is not duplication for its own sake — it is the wire format being
+ * honest about what it is. `GraphModel` is an *internal* core type, free to
+ * change shape when core needs it to. What crosses an HTTP boundary is a
+ * *contract*, and a contract that silently reshapes itself whenever an
+ * internal type is refactored is not a contract. Declaring it separately
+ * means a core change that would break the client is a visible, deliberate
+ * edit here rather than an invisible one.
+ *
+ * The obvious risk of a copy is drift, so drift is a **compile error**:
+ * `tests/web/wire.contract.test.ts` asserts mutual assignability between
+ * every type here and its core counterpart. That test is Node-side, where
+ * importing core is legal and free. Add a field to `GraphNode` in core and
+ * that test fails to compile until this file agrees — which is exactly the
+ * moment a human should be deciding whether the new field belongs on the
+ * wire.
+ *
+ * Isomorphic: no `node:*`, no DOM, no `src/core`, no `src/pi`.
+ */
+
+/**
+ * Where a piece of knowledge came from. Drives trust display (design §13).
+ *
+ * Mirrors `NoteSource` in `src/core/types.ts`.
+ */
+export type WireNoteSource = "human" | "agent" | "generated";
+
+/** Mirrors `StalenessState` in `src/core/types.ts`. */
+export type WireStalenessState = "missing" | "fresh" | "stale";
+
+/** Mirrors `StalenessReport` in `src/core/types.ts`. */
+export interface WireStalenessReport {
+  state: WireStalenessState;
+  reasons: string[];
+}
+
+/** Mirrors `NodeKind` in `src/core/graph/model.ts`. */
+export type WireNodeKind =
+  | "vault"
+  | "note"
+  | "repository"
+  | "module"
+  | "package"
+  | "entryPoint"
+  | "gitState"
+  | "external"
+  | "file";
+
+/** Mirrors `EdgeKind` in `src/core/graph/model.ts`. */
+export type WireEdgeKind = "contains" | "anchored-at" | "links-to" | "mentions";
+
+/**
+ * Every node kind. The graph legend and the table tests iterate this.
+ *
+ * A runtime value, unlike everything else in this file, because a renderer
+ * needs to enumerate kinds to build a legend and a `type` cannot be iterated.
+ * The contract test pins it against core's `NODE_KINDS` element-for-element,
+ * so a kind added to core and not here is a failing test rather than a
+ * legend that quietly omits a colour.
+ */
+export const WIRE_NODE_KINDS: readonly WireNodeKind[] = [
+  "vault",
+  "note",
+  "repository",
+  "module",
+  "package",
+  "entryPoint",
+  "gitState",
+  "external",
+  "file",
+];
+
+/** Every edge kind. Same reasoning as {@link WIRE_NODE_KINDS}. */
+export const WIRE_EDGE_KINDS: readonly WireEdgeKind[] = ["contains", "anchored-at", "links-to", "mentions"];
+
+/**
+ * A single graph node. `id` is stable: derived from slugs and paths only.
+ *
+ * Mirrors `GraphNode` in `src/core/graph/model.ts`.
+ */
+export interface WireGraphNode {
+  id: string;
+  kind: WireNodeKind;
+  label: string;
+  /** Trust provenance for knowledge nodes; `null` for structural nodes. */
+  provenance: WireNoteSource | null;
+  /** Pre-formatted side-panel payload. Display-only by contract. */
+  detail: Record<string, string>;
+}
+
+/** Mirrors `GraphEdge` in `src/core/graph/model.ts`. */
+export interface WireGraphEdge {
+  source: string;
+  target: string;
+  kind: WireEdgeKind;
+}
+
+/**
+ * The authoritative node/edge data, as delivered to the browser.
+ *
+ * Mirrors `GraphModel` in `src/core/graph/model.ts`, **narrowed by one
+ * field**: core's `danglingLinks` (§4.2) is not repeated here.
+ *
+ * §2.1 allows a wire type to be deliberately narrower than its core
+ * counterpart provided the narrowing is *declared* rather than discovered,
+ * and this is that declaration. The reason is `GraphPayload` (§5.3): the
+ * payload already hoists that index to its own top level as `dangling`, so
+ * mirroring it inside `model` as well would put the same map on the wire
+ * twice and give the client two places to read one fact from.
+ *
+ * Two things keep the narrowing honest rather than aspirational.
+ * `tests/web/wire.contract.test.ts` asserts
+ * `Exact<WireGraphModel, Omit<GraphModel, "danglingLinks">>` — still mutual
+ * assignability, merely against an explicitly reduced core type, so a
+ * *second* core field added and forgotten still fails to compile. And
+ * `toGraphPayload` strips the key at the single point that builds the
+ * payload, because TypeScript's structural typing would otherwise let the
+ * extra property ride along into `JSON.stringify`.
+ */
+export interface WireGraphModel {
+  /**
+   * Data-as-of marker derived from inputs (max note `updated` / index stamp),
+   * so two builds of unchanged inputs produce byte-identical JSON. That is
+   * the property `GraphPayload.stamp` and the `304` path depend on.
+   */
+  generatedAt: string;
+  staleness: WireStalenessReport | null;
+  nodes: WireGraphNode[];
+  edges: WireGraphEdge[];
+  /**
+   * Content fingerprint of the note bodies (see core `GraphModel`). Rides
+   * the wire so `GraphPayload.stamp` — hashed over these bytes — moves on a
+   * body-only edit, which is what un-dedupes the SSE frame that refetches
+   * an open note.
+   */
+  contentDigest: string;
+}
+
+/**
+ * The core `GraphModel` keys {@link WireGraphModel} deliberately omits.
+ *
+ * A runtime value rather than only a comment, for the same reason
+ * {@link WIRE_NODE_KINDS} is one: the server has to actually delete these
+ * keys before serializing, and a hand-written second list of them at the
+ * emit site is a list that drifts. `toGraphPayload` iterates this.
+ */
+export const WIRE_MODEL_OMITTED_KEYS: readonly string[] = ["danglingLinks"];
+
+/**
+ * One note, read live for the note column.
+ *
+ * Mirrors `ViewNote` in `src/core/graph/current.ts`.
+ */
+export interface WireViewNote {
+  slug: string;
+  title: string;
+  body: string;
+  created: string;
+  updated: string;
+  tags: string[];
+  source: WireNoteSource;
+}
+
+/** Mirrors `NoteMeta` in `src/core/types.ts`. */
+export interface WireNoteMeta {
+  title: string;
+  /** ISO-8601 timestamps. */
+  created: string;
+  updated: string;
+  tags: string[];
+  source: WireNoteSource;
+}
+
+/** Mirrors `NoteSummary` in `src/core/types.ts`. */
+export interface WireNoteSummary extends WireNoteMeta {
+  /** File-name slug (no extension). Stable identity of the note. */
+  slug: string;
+  /** Size of the Markdown body in characters. */
+  bodyLength: number;
+}
+
+/** Mirrors `NoteSearchHit` in `src/core/types.ts`. */
+export interface WireNoteSearchHit {
+  summary: WireNoteSummary;
+  score: number;
+  snippet: string;
+}

package/src/web/shared/layout.ts

@@ -0,0 +1,314 @@
+/**
+ * Force-directed layout: `GraphModel` → `Map<id, Point>` (weave-workspace §7).
+ *
+ * Isomorphic by contract (§2 tier table): this module runs in Node — the
+ * server precomputes positions for `GraphPayload.positions`, and the dynamics
+ * gate exercises it headless — and in the browser, where the client re-runs it
+ * on drag and expand/collapse. It therefore imports **only** `d3-force` and
+ * the wire DTOs from `./graph`. No `node:*`, no DOM, no `src/pi`, no
+ * `src/core`.
+ *
+ * It used to take its graph types from `src/core/graph/model` as `import
+ * type`. That was legal under the §2 table and still wrong: §7.1 has
+ * `src/web/client/graph/project.ts` consuming this module, and the day that
+ * lands, resolving a core type would drag the whole `node:fs`-flavoured core
+ * type graph into `tsconfig.web.json` — the identical failure `wire.ts` hit.
+ * Fixed here pre-emptively rather than left as a tripwire for P3.
+ *
+ * ## The recipe — d3's own force-directed tree, not ours
+ *
+ * This module used to carry ~250 lines of derived geometry: a ring-radius
+ * formula per hub fan-out, hash-angled seed rings, a disc-packed root ring,
+ * and seed-anchored gravity. All of it existed to shape a force simulation
+ * into a readable tree. d3's own force-directed-tree example does that in five
+ * lines:
+ *
+ * ```js
+ * const root = d3.hierarchy(data);
+ * const links = root.links();
+ * const nodes = root.descendants();
+ *
+ * const simulation = d3.forceSimulation(nodes)
+ *     .force("link", d3.forceLink(links).id(d => d.id).distance(0).strength(1))
+ *     .force("charge", d3.forceManyBody().strength(-50))
+ *     .force("x", d3.forceX())
+ *     .force("y", d3.forceY());
+ * ```
+ *
+ * The containment tree wants children at their parent with full strength, and
+ * the picture emerges from gentle repulsion and collision. The property that
+ * matters: a tree's radius is set by its **depth**, not by any single node's
+ * fan-out — a 188-child directory shares the angular space with its siblings
+ * instead of defining a ring that the whole graph has to fit inside. That is
+ * why the retired ring-radius family (`ringRadius`, `RING_CAP`,
+ * `seedPositions`, `clusterGap`, `rootRingRadius`, `arcShare`, `rootAngles`
+ * and the seed-anchored gravity) is deleted rather than tuned: it was a wheel
+ * d3 already ships.
+ *
+ * Two deviations from the example, both stated rather than hidden:
+ *
+ * 1. **`forceCollide`** — the example draws 3.5-pixel dots with no labels; we
+ *    draw 9-unit nodes with zoomed labels, so nodes keep a collision radius
+ *    (`NODE_RADIUS + label room`) and siblings never overlap.
+ * 2. **Relation edges** (`links-to` / `mentions`) are not part of the tree.
+ *    They ride along at a longer distance and a fraction of the strength, so
+ *    they decorate the structure instead of distorting it.
+ *
+ * `forceX()`/`forceY()` (d3 defaults: target 0, no accessor) replace the
+ * seed-anchored gravity — they pull every component toward the origin, which
+ * is the no-component-escapes-to-infinity guarantee the anchors existed for,
+ * and they mean a released drag needs no anchor bookkeeping at all.
+ *
+ * ## Why d3-force (§7.2)
+ *
+ * The retired simulation collapsed to a vertical line because repulsion and
+ * collision derive their direction as `dx / d`: once two nodes share an `x`,
+ * the x-component of the push is exactly zero forever, and damping freezes it
+ * there. d3-force injects `jiggle()` on exactly that zero (`manyBody.js`,
+ * `collide.js`, `link.js`), drawn from a **seeded** LCG — so we get symmetry
+ * breaking *and* reproducibility, which is what makes §8 a stable CI gate
+ * rather than a flaky one. d3 also fills nodes without positions on a
+ * deterministic phyllotaxis spiral, so cold starts need no invented seeding.
+ */
+
+import { forceCollide, forceLink, forceManyBody, forceSimulation, forceX, forceY } from "d3-force";
+import type { Simulation, SimulationLinkDatum, SimulationNodeDatum } from "d3-force";
+import type { WireEdgeKind as EdgeKind, WireGraphEdge as GraphEdge, WireGraphModel as GraphModel } from "./graph";
+import type { Point } from "./metrics";
+
+export type { Point } from "./metrics";
+
+export interface LayoutOptions {
+  /** Simulation steps. Alpha decay is derived from this, so the budget stays meaningful. Default 300. */
+  ticks?: number;
+  /** Seeds d3's jiggle LCG. Default 1. */
+  seed?: number;
+  /**
+   * Warm-start positions by node id. The client passes current positions when
+   * re-running after a drag or an expand so the graph does not jump; the
+   * dynamics gate passes coincident points to prove symmetry breaking. Ids
+   * absent here start on d3's own deterministic phyllotaxis spiral.
+   */
+  initial?: ReadonlyMap<string, Point>;
+  /**
+   * Hold the warm-started nodes in place while the simulation integrates the
+   * newcomers (d3's `fx`/`fy`). The collapse/expand pattern: an expand must
+   * hand its new children to the layout without shoving everything else out
+   * of the way — the existing arrangement is the user's, and the collide
+   * force packs the newcomers around it. Ignored without `initial`.
+   */
+  pinWarm?: boolean;
+}
+
+/** Visual node radius in layout units. The renderer must not draw larger than this. */
+export const NODE_RADIUS = 9;
+
+/** Collision radius: the node plus breathing room for the leading edge of its label. */
+export const COLLIDE_RADIUS = NODE_RADIUS + 9;
+
+/** `links-to` / `mentions` are associative, not structural: longer and weak. */
+const RELATION_DISTANCE = 220;
+
+/** Relation edges pull at a fraction of the containment link's strength — decoration, not structure. */
+const RELATION_STRENGTH = 0.05;
+
+/** Body repulsion — the force-directed-tree example's own value. */
+const CHARGE_STRENGTH = -50;
+
+/**
+ * The containment tree's spring: rest length and stiffness.
+ *
+ * The example's `distance(0).strength(1)` is rigid — correct for 3.5-pixel
+ * dots with no collide, and violent here: with a collision radius and a
+ * 189-child hub, dragging the hub yanked every child at full strength and the
+ * whole tree thrashed (measured: >9000 units of other-node motion per tick on
+ * this repository's real graph). Springs with real rest length and low
+ * stiffness keep every drag a local ripple while collide still packs the
+ * cluster; the shape stays a tree because every node is *in* the tree, not
+ * because the links are rigid.
+ */
+const CONTAINS_REST = 90;
+const CONTAINS_STRENGTH = 0.02;
+
+const DEFAULT_TICKS = 300;
+const DEFAULT_SEED = 1;
+
+/** d3-force's own alpha floor (`simulation.js`); mirrored so `alphaDecay` can be derived from `ticks`. */
+const ALPHA_MIN = 0.001;
+
+interface SimNode extends SimulationNodeDatum {
+  id: string;
+  x?: number;
+  y?: number;
+}
+
+interface SimLink extends SimulationLinkDatum<SimNode> {
+  source: string | SimNode;
+  target: string | SimNode;
+  kind: EdgeKind;
+}
+
+/** Containment edges define the hierarchy; everything else is an association. */
+export function isContainment(kind: EdgeKind): boolean {
+  return kind === "contains" || kind === "anchored-at";
+}
+
+/**
+ * d3-force's LCG (`lcg.js`: a = 1664525, c = 1013904223, m = 2³²), re-exposed
+ * so `seed` actually selects a stream — d3 always builds its own with s = 1,
+ * and `simulation.randomSource()` is the documented way to replace it.
+ */
+export function lcg(seed: number): () => number {
+  let s = Math.trunc(seed) >>> 0;
+  return () => (s = (1664525 * s + 1013904223) % 4294967296) / 4294967296;
+}
+
+interface Structure {
+  /** Ids in `model.nodes` order, deduped. */
+  ids: string[];
+  /** Edges with both endpoints present, no self-loops, deduped. */
+  edges: GraphEdge[];
+}
+
+/**
+ * Normalise the model into something a simulation can consume: drop self-edges
+ * and edges pointing at ids that are not nodes (d3's `forceLink` throws on
+ * those), and dedupe. Malformed input is the caller's bug, but it must not be
+ * the layout's crash.
+ */
+function analyse(model: GraphModel): Structure {
+  const ids: string[] = [];
+  const known = new Set<string>();
+  for (const n of model.nodes) {
+    if (known.has(n.id)) continue;
+    known.add(n.id);
+    ids.push(n.id);
+  }
+
+  const edges: GraphEdge[] = [];
+  const seen = new Set<string>();
+  for (const e of model.edges) {
+    if (e.source === e.target) continue;
+    if (!known.has(e.source) || !known.has(e.target)) continue;
+    const key = `${e.source}\u0000${e.target}\u0000${e.kind}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    edges.push(e);
+  }
+  return { ids, edges };
+}
+
+/**
+ * Lay a graph out. Deterministic: the same model with the same `seed` produces
+ * byte-identical output, in Node or the browser.
+ *
+ * The simulation is stepped **synchronously** — `stop()` then a manual `tick()`
+ * loop — so it never touches `requestAnimationFrame` and works headless.
+ * Warm ids keep their positions; ids without one start on d3's deterministic
+ * phyllotaxis spiral, which is why a cold start needs no invented seeding.
+ */
+export function computeLayout(model: GraphModel, options: LayoutOptions = {}): Map<string, Point> {
+  const ticks = Math.max(0, Math.trunc(options.ticks ?? DEFAULT_TICKS));
+  const seed = options.seed ?? DEFAULT_SEED;
+
+  const { ids, edges } = analyse(model);
+  const out = new Map<string, Point>();
+  if (ids.length === 0) return out;
+
+  const warm = options.initial;
+  const nodes: SimNode[] = ids.map((id) => {
+    const at = warm?.get(id);
+    const node: SimNode = { id, vx: 0, vy: 0 };
+    if (at !== undefined && Number.isFinite(at.x) && Number.isFinite(at.y)) {
+      node.x = at.x;
+      node.y = at.y;
+      if (options.pinWarm === true) {
+        node.fx = at.x;
+        node.fy = at.y;
+      }
+    }
+    return node;
+  });
+
+  if (nodes.length > 1) {
+    runSimulation(nodes, edges, { ticks, seed, warm: warm !== undefined });
+  }
+  // A pinned run leaves the pins behind; clear them so the returned map is
+  // positions, not a promise to keep standing there forever.
+  if (options.pinWarm === true) for (const n of nodes) { n.fx = null; n.fy = null; }
+
+  for (const n of nodes) {
+    // Guarded on the way out as well as in: the contract is that no caller
+    // ever receives a NaN. d3 fills every node during `initialize`, so the
+    // fallback is unreachable in practice — but the contract is the contract.
+    out.set(n.id, { x: Number.isFinite(n.x as number) ? (n.x as number) : 0, y: Number.isFinite(n.y as number) ? (n.y as number) : 0 });
+  }
+  return out;
+}
+
+export interface ForceSimulationOptions<N> {
+  nodes: N[];
+  /** String endpoints are resolved by node id; dangling ids must be filtered out by the caller. */
+  links: Array<{ source: string | N; target: string | N; kind: EdgeKind }>;
+  /**
+   * Per-node `forceX`/`forceY` targets, re-read every tick. Absent (or an id
+   * missing from the map) targets the origin — d3's own default — which is the
+   * no-component-escapes guarantee. A live driver mutates the map on drag
+   * release so a dropped node rests where the user put it.
+   */
+  anchors?: ReadonlyMap<string, Point>;
+  /** Seeds d3's jiggle LCG. Default 1 — deterministic in Node and browser. */
+  seed?: number;
+}
+
+/**
+ * The force configuration, as ONE definition shared by the static layout
+ * ({@link computeLayout}) and the live driver (`dynamics.ts`).
+ *
+ * It is d3's force-directed-tree recipe: the containment tree holds children
+ * at their parent with full strength, and the arrangement emerges from gentle
+ * repulsion and collision; `forceX()`/`forceY()` pull every component toward
+ * the origin at d3's default strength, so nothing drifts to infinity.
+ *
+ * The forces live here once so the static and live equilibria cannot diverge:
+ * whatever the static layout settles to is exactly what the live sim holds.
+ * The simulation is returned stopped; the driver owns the alpha policy — the
+ * static path decays to the alpha floor over its tick budget, the live path
+ * re-heats on interaction and sleeps when the floor is reached. Velocity
+ * decay stays at d3's own default, exactly like the example.
+ */
+export function createForceSimulation<
+  N extends SimulationNodeDatum & { id: string },
+>(opts: ForceSimulationOptions<N>): Simulation<N, undefined> {
+  const link = forceLink<N, { source: string | N; target: string | N; kind: EdgeKind }>(opts.links)
+    .id((n) => n.id)
+    .distance((l) => (isContainment(l.kind) ? CONTAINS_REST : RELATION_DISTANCE))
+    .strength((l) => (isContainment(l.kind) ? CONTAINS_STRENGTH : RELATION_STRENGTH))
+    .iterations(2);
+
+  return forceSimulation<N>(opts.nodes)
+    .randomSource(lcg(opts.seed ?? DEFAULT_SEED))
+    .force("charge", forceManyBody<N>().strength(CHARGE_STRENGTH))
+    .force("link", link)
+    .force("collide", forceCollide<N>(COLLIDE_RADIUS).strength(1).iterations(3))
+    .force("x", forceX<N>((n) => opts.anchors?.get(n.id)?.x ?? 0))
+    .force("y", forceY<N>((n) => opts.anchors?.get(n.id)?.y ?? 0))
+    .stop();
+}
+
+/** Configure and step the d3 simulation in place. Mutates `nodes`. */
+function runSimulation(nodes: SimNode[], edges: readonly GraphEdge[], opts: { ticks: number; seed: number; warm: boolean }): void {
+  const links: SimLink[] = edges.map((e) => ({ source: e.source, target: e.target, kind: e.kind }));
+  const sim = createForceSimulation({ nodes, links, seed: opts.seed });
+  sim
+    // A cold start assembles from d3's phyllotaxis at full alpha; a warm start
+    // relaxes what is already on screen — d3's own re-heat value — so the
+    // graph does not re-arrange itself under the user on every expand.
+    .alpha(opts.warm ? 0.3 : 1)
+    .alphaMin(ALPHA_MIN)
+    // Reach the same convergence at whatever tick budget the caller asked for.
+    // Velocity decay stays at d3's own default — the example sets neither.
+    .alphaDecay(opts.ticks > 0 ? 1 - Math.pow(ALPHA_MIN, 1 / opts.ticks) : 0);
+
+  for (let i = 0; i < opts.ticks; i++) sim.tick();
+}

package/src/web/shared/logo.ts

@@ -0,0 +1,11 @@
+/**
+ * logo.ts — the pi-weave brand mark as an inline data URI.
+ *
+ * The web viewer is a single committed bundle behind a strict CSP
+ * (img-src 'self' data:), so the brand mark is an inlined 48×48 PNG —
+ * the transparent-background spider derived from docs/pi-weave-logo.png —
+ * rather than a new static route. Same pattern as the TUI's branding.ts.
+ */
+export const LOGO_MARK_MIME = "image/png";
+/** 48×48 transparent PNG, base64 — crisp at 2× for the 18px header mark. */
+export const LOGO_MARK_B64 = "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";

package/src/web/shared/metrics.ts

@@ -0,0 +1,136 @@
+/**
+ * Pure geometry over a laid-out point set (weave-workspace §8).
+ *
+ * These are the measurements the dynamics gate asserts on, and the same
+ * measurements the graph column needs at runtime (`bbox` is what "fit to
+ * view" is built from). They live in `src/web/shared` rather than in the
+ * test tree so they are covered code, not untested test scaffolding.
+ *
+ * Isomorphic: no `node:*`, no DOM.
+ */
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface BBox {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+  w: number;
+  h: number;
+  cx: number;
+  cy: number;
+}
+
+/** The empty bounding box: zero-sized at the origin. */
+const EMPTY_BBOX: BBox = { minX: 0, minY: 0, maxX: 0, maxY: 0, w: 0, h: 0, cx: 0, cy: 0 };
+
+/**
+ * Population variance. Zero for an empty or single-element sample, and — the
+ * case that matters — exactly zero for the degenerate "every node on one
+ * vertical line" layout that the retired simulation produced.
+ */
+export function variance(values: readonly number[]): number {
+  const n = values.length;
+  if (n < 2) return 0;
+  let sum = 0;
+  for (const v of values) sum += v;
+  const mean = sum / n;
+  let acc = 0;
+  for (const v of values) {
+    const d = v - mean;
+    acc += d * d;
+  }
+  return acc / n;
+}
+
+/**
+ * Smallest Euclidean distance between any two distinct points. `Infinity` for
+ * fewer than two points (vacuously non-overlapping).
+ *
+ * O(n²). The gate runs it on a few hundred points, which is microseconds; if
+ * a caller ever needs it on tens of thousands, sort-and-sweep it then.
+ */
+export function minPairwiseDistance(points: readonly Point[]): number {
+  let min = Infinity;
+  let i = 0;
+  // `for…of` over a slice rather than indexing: `noUncheckedIndexedAccess`
+  // would otherwise force an `undefined` guard on every access that can never
+  // fire, and an untestable branch is worse than a copy of a few hundred refs.
+  for (const a of points) {
+    i++;
+    for (const b of points.slice(i)) {
+      const dx = a.x - b.x;
+      const dy = a.y - b.y;
+      const d = Math.sqrt(dx * dx + dy * dy);
+      if (d < min) min = d;
+    }
+  }
+  return min;
+}
+
+/** Axis-aligned bounding box, with width/height/centre precomputed. */
+export function bbox(points: readonly Point[]): BBox {
+  if (points.length === 0) return EMPTY_BBOX;
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const p of points) {
+    if (p.x < minX) minX = p.x;
+    if (p.x > maxX) maxX = p.x;
+    if (p.y < minY) minY = p.y;
+    if (p.y > maxY) maxY = p.y;
+  }
+  return { minX, minY, maxX, maxY, w: maxX - minX, h: maxY - minY, cx: (minX + maxX) / 2, cy: (minY + maxY) / 2 };
+}
+
+/**
+ * How far apart the cluster anchors ended up: the smallest distance between
+ * any two of `ids` in `positions`. Ids with no position are skipped; fewer
+ * than two resolvable anchors yields `Infinity`.
+ *
+ * "The five roots stay distinct" is exactly this number staying large — if two
+ * clusters merge, their anchors are the first thing to collide.
+ */
+export function clusterSeparation(positions: ReadonlyMap<string, Point>, ids: readonly string[]): number {
+  const anchors: Point[] = [];
+  for (const id of ids) {
+    const p = positions.get(id);
+    if (p !== undefined) anchors.push(p);
+  }
+  return minPairwiseDistance(anchors);
+}
+
+/**
+ * How many of `sectors` equal angular slices around `center` contain at least
+ * one of `points`. Points at the exact centre have no angle and are skipped.
+ *
+ * This is the difference between "a hub's leaves ring it" (occupancy →
+ * `sectors`) and "a hub's leaves fell into a line" (occupancy → 2). A count,
+ * not a ratio, because the interesting failure is whole sectors being empty.
+ */
+export function angularOccupancy(center: Point, points: readonly Point[], sectors: number): number {
+  const hit = new Set<number>();
+  const TAU = Math.PI * 2;
+  for (const p of points) {
+    const dx = p.x - center.x;
+    const dy = p.y - center.y;
+    if (dx === 0 && dy === 0) continue;
+    // atan2 ∈ (-π, π] → [0, 1) → sector index, clamped against the +π edge.
+    const unit = (Math.atan2(dy, dx) + Math.PI) / TAU;
+    hit.add(Math.min(sectors - 1, Math.floor(unit * sectors)));
+  }
+  return hit.size;
+}
+
+/** True when every coordinate of every point is a finite number. */
+export function allFinite(points: readonly Point[]): boolean {
+  for (const p of points) {
+    if (!Number.isFinite(p.x) || !Number.isFinite(p.y)) return false;
+  }
+  return true;
+}