beadcyte 0.4.0

package/src/web/triage.ts

@@ -0,0 +1,914 @@
+// triage.ts — a local reimplementation of the scoring bv documents for
+// --robot-triage.
+//
+// bv's triage combines eight normalized signals over the bead dependency
+// graph into a single 0..1 score used to rank actionable work:
+//
+//   score = 0.22·pagerank + 0.20·betweenness + 0.13·blocker_ratio
+//         + 0.05·staleness + 0.10·priority_boost + 0.10·time_to_impact
+//         + 0.10·urgency + 0.10·risk
+//
+// The weights above are lifted from actual bv output (see
+// __fixtures__/bv-triage.json for a captured sample from this repo). The
+// per-signal computations are best-effort reproductions of bv's documented
+// behaviour — numerical parity is a *goal* (see triage.test.mjs cross-
+// check), not a contract; if bv changes its formula the ordering will
+// remain sensible but individual values may drift.
+//
+// Provenance: written independently, in TypeScript, from bv's documented
+// behaviour and the captured output above. bv's Go source was offered as a
+// reference only after this file existed, and only to check parity; no code
+// was transcribed from it. bv is MIT with an additional rider (bp-67g.61).
+//
+// How close we actually are was measured for bp-67g.23 and is recorded in
+// SIGNAL_FIDELITY below, signal by signal. Four of eight match bv; three
+// diverge and are bp-67g.37's problem; one (risk) is only partly
+// computable. Read that table before trusting a number out of here — and
+// note that a WEIGHT is not what a signal can contribute, because two of
+// the norms are bounded well below 1.
+//
+// Pure, no I/O — consumers wrap this in a Pinia getter over raw beads.
+
+import type { Bead } from "./store";
+
+// ── weights ───────────────────────────────────────────────────────────────
+
+export const TRIAGE_WEIGHTS = {
+  pagerank: 0.22,
+  betweenness: 0.20,
+  blocker_ratio: 0.13,
+  staleness: 0.05,
+  priority_boost: 0.10,
+  time_to_impact: 0.10,
+  urgency: 0.10,
+  risk: 0.10,
+} as const;
+
+export type TriageSignal = keyof typeof TRIAGE_WEIGHTS;
+
+const MS_PER_DAY = 86_400_000;
+
+/** A bead untouched this long is maximally stale. bv's horizon. */
+const STALENESS_HORIZON_DAYS = 30;
+
+/** Depth beyond this stops adding to time-to-impact. */
+const MAX_CRITICAL_PATH_DEPTH = 10;
+
+/** Time-to-impact's time factor is measured against a working day. */
+const MINUTES_PER_WORKDAY = 480;
+
+/** Half-life of the urgency decay term, in days. */
+const URGENCY_HALF_LIFE_DAYS = 7;
+
+/**
+ * Assumed minutes of work per bead when no estimate is passed in. 240 is
+ * half a working day, which is what our estimator currently returns for
+ * almost every bead (bp-67g.24).
+ */
+const DEFAULT_ESTIMATE_MINUTES = 240;
+
+/**
+ * Labels that declare urgency, and what each is worth. Substring matched,
+ * so `priority::critical` and `critical` both hit.
+ */
+const URGENCY_LABELS: ReadonlyArray<{ match: string; weight: number }> = [
+  { match: "critical", weight: 1.0 },
+  { match: "blocker", weight: 1.0 },
+  { match: "urgent", weight: 0.8 },
+  { match: "hotfix", weight: 0.8 },
+  { match: "asap", weight: 0.6 },
+];
+
+const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
+
+/**
+ * What each weight is actually worth, and how faithful our computation is.
+ *
+ * A weight states what a signal COULD contribute. Two of ours cannot reach
+ * it, because their norms are bounded well below 1 — so the weight column
+ * in the drawer was promising 0.10 where 0.026 was the ceiling. This is the
+ * table that keeps that honest, and it is checked against bv in
+ * triage.test.mjs rather than asserted here.
+ *
+ * `fidelity`:
+ *   "faithful"  verified equal to bv on the captured fixture
+ *   "partial"   we compute part of bv's model; the rest is unavailable
+ *   "local"     deliberately ours, and known to differ from bv
+ *
+ * Measured for bp-67g.23 against __fixtures__/bv-triage.json and a live
+ * `bv --robot-triage` on a 577-bead repo. The three "local" entries are
+ * bp-67g.37's problem, not this table's.
+ */
+export const SIGNAL_FIDELITY: Record<
+  TriageSignal,
+  { max: number; fidelity: "faithful" | "partial" | "local"; note?: string }
+> = {
+  pagerank: {
+    max: 1,
+    fidelity: "local",
+    note: "same max-normalisation as bv, but our PageRank orders beads differently (bp-67g.37)",
+  },
+  betweenness: { max: 1, fidelity: "faithful" },
+  blocker_ratio: { max: 1, fidelity: "faithful" },
+  staleness: { max: 1, fidelity: "faithful" },
+  priority_boost: { max: 1, fidelity: "faithful" },
+  time_to_impact: {
+    max: 1,
+    fidelity: "partial",
+    note: "depth is ours; the time factor uses one repo-wide estimate, not per bead (bp-67g.24)",
+  },
+  urgency: { max: 1, fidelity: "faithful" },
+  risk: {
+    max: 0.8,
+    fidelity: "partial",
+    note: "cross-repo risk has nothing to measure in a single-repo workspace, so 0.20 of the composite is unclaimed",
+  },
+};
+
+/**
+ * The most this signal can contribute to a score — weight x achievable max,
+ * not weight alone. `risk` declares 0.10 and can contribute 0.002.
+ */
+export function achievableContribution(signal: TriageSignal): number {
+  return TRIAGE_WEIGHTS[signal] * SIGNAL_FIDELITY[signal].max;
+}
+
+// ── what each signal measures, in the words of the code below ─────────────
+// Rendered on the signal names in the drawer (bp-67g.47). Built from the
+// same constants the norm functions use — the horizon, the half-life, the
+// workday, the depth cap, the urgency labels — so a change to any of them
+// reaches the sentence without anyone remembering to edit prose. Change a
+// formula, change its sentence here, in the same commit: that is the rule.
+
+export function explainSignal(signal: TriageSignal): string {
+  switch (signal) {
+    case "pagerank":
+      return "How much of the dependency graph flows through this bead: PageRank over the blocks edges, so a bead that unblocks beads which themselves unblock many others scores high. Scaled so the largest value among this repo's beads is 1.";
+    case "betweenness":
+      return "How often this bead sits on the shortest dependency path between two other beads (Brandes' betweenness), scaled so the largest value in the repo is 1. A bottleneck between two clusters of work scores high.";
+    case "blocker_ratio":
+      return "How many beads this one directly blocks, against the busiest blocker in the repo. A count of direct edges, not the length of the chain behind them.";
+    case "staleness":
+      return `Days since the bead was last updated, as a share of a ${STALENESS_HORIZON_DAYS}-day horizon: untouched for ${STALENESS_HORIZON_DAYS} days or more reads 1.`;
+    case "priority_boost":
+      return "Priority as a boost: P0 reads 1.0 and P4 reads 0.0, in quarter steps. A deferred bead reads 0 whatever its priority.";
+    case "time_to_impact":
+      return `0.7 × how deep the chain of live work this bead releases is (its height among open dependents, against ${MAX_CRITICAL_PATH_DEPTH}) plus 0.3 × how short the work is against a ${MINUTES_PER_WORKDAY / 60}-hour day. The work length is one repo-wide estimate, not this bead's own. Short work at the head of a long chain scores high.`;
+    case "urgency":
+      return `An urgency label scores its weight (${URGENCY_LABELS.map((u) => `${u.match} ${u.weight}`).join(", ")}), plus an age term rising toward 0.5 the longer the bead stays unresolved, with a ${URGENCY_HALF_LIFE_DAYS}-day half-life from creation. Capped at 1.`;
+    case "risk":
+      return "0.30 × fan variance (how unevenly depended-on this bead's own blockers are) + 0.30 × activity churn (comments and edits relative to its age) + 0.20 × status risk (blocked is worst, blocked and idle worse; in progress only once it stops moving). The remaining 0.20, cross-repo risk, has nothing to measure in one repo and is left unclaimed, so risk tops out at 0.8. A closed bead reads 0.";
+  }
+}
+
+/** "0.22·pagerank + 0.20·betweenness + …", from the weights themselves. */
+export function describeComposite(): string {
+  return (Object.keys(TRIAGE_WEIGHTS) as TriageSignal[])
+    .map((k) => `${TRIAGE_WEIGHTS[k].toFixed(2)}·${k}`)
+    .join(" + ");
+}
+
+/** The headline score, for the drawer's "triage score" label. */
+export function explainScore(): string {
+  return `A weighted sum of eight signals, each scaled 0–1 first: ${describeComposite()}. The percentage is that sum; the breakdown below shows what each signal contributed and how it is measured.`;
+}
+
+// ── shapes ────────────────────────────────────────────────────────────────
+
+export interface TriageBreakdown {
+  pagerank: number;
+  betweenness: number;
+  blocker_ratio: number;
+  staleness: number;
+  priority_boost: number;
+  time_to_impact: number;
+  urgency: number;
+  risk: number;
+  pagerank_norm: number;
+  betweenness_norm: number;
+  blocker_ratio_norm: number;
+  staleness_norm: number;
+  priority_boost_norm: number;
+  time_to_impact_norm: number;
+  urgency_norm: number;
+  risk_norm: number;
+}
+
+export interface TriageResult {
+  score: number;
+  breakdown: TriageBreakdown;
+}
+
+// ── main entry point ──────────────────────────────────────────────────────
+
+/**
+ * Compute triage for every bead in the passed array. Brandes' betweenness
+ * is O(V·E) worst case, but over typed arrays with dangling sources skipped
+ * it measures ~5ms in node on a 600-bead graph (bp-67g.25: it was ~67ms
+ * there and ~300ms in the browser before), so the first drawer open no
+ * longer stalls on it.
+ */
+export function computeTriage(
+  beads: Bead[],
+  opts: { now?: Date; estimateMinutes?: number } = {},
+): Map<string, TriageResult> {
+  const now = (opts.now ?? new Date()).getTime();
+  // Minutes of work assumed per bead, for time_to_impact's time factor.
+  // A single figure rather than per-bead because our estimator currently
+  // returns one for almost everything (bp-67g.24); when that is fixed this
+  // wants to become a per-bead lookup.
+  const estimateMinutes = opts.estimateMinutes ?? DEFAULT_ESTIMATE_MINUTES;
+  const byId = new Map(beads.map((b) => [b.id, b] as const));
+
+  // Adjacency: for each bead, who does it BLOCK (outgoing) and who blocks it
+  // (incoming). Non-`blocks` deps are ignored — the graph is only the
+  // work-ordering DAG.
+  const outgoing = new Map<string, string[]>();
+  const incoming = new Map<string, string[]>();
+  for (const b of beads) {
+    outgoing.set(b.id, []);
+    incoming.set(b.id, []);
+  }
+  for (const b of beads) {
+    for (const d of b.dependencies ?? []) {
+      if (d.type !== "blocks") continue;
+      const blockerId = d.depends_on_id;
+      if (!byId.has(blockerId)) continue;
+      // "b depends on blockerId" ⇒ blockerId BLOCKS b ⇒ edge blockerId → b.
+      outgoing.get(blockerId)!.push(b.id);
+      incoming.get(b.id)!.push(blockerId);
+    }
+  }
+
+  // Only OPEN beads participate meaningfully in triage ranking. Closed
+  // beads still exist in the graph (their edges matter for readiness) but
+  // shouldn't get a score of their own — the caller can filter them out
+  // downstream. We compute a score for everything and let consumers decide.
+  const rawPageRank = pageRank(beads, outgoing);
+  const rawBetweenness = betweennessCentrality(beads, outgoing);
+
+  // Blocker ratio: how much this bead unblocks, in direct-degree terms.
+  const rawBlockerRatio = new Map<string, number>();
+  for (const b of beads) {
+    rawBlockerRatio.set(b.id, outgoing.get(b.id)!.length);
+  }
+
+  // Longest blocking chain ending at each bead — height in the DAG, which
+  // is what time_to_impact's depth term needs. A bead with no blocking
+  // edges at all is 0; anything in the graph is 1 + its deepest blocker.
+  const depth = graphHeights(beads, byId);
+
+  // In-degree per bead, for risk's fan-variance term.
+  const inDegree = new Map<string, number>();
+  for (const b of beads) inDegree.set(b.id, incoming.get(b.id)!.length);
+
+  // Global maxima for normalization (avoid divide-by-zero when the graph
+  // has no signal on a dimension).
+  const maxPageRank = maxOf(rawPageRank);
+  const maxBetweenness = maxOf(rawBetweenness);
+  const maxBlockerRatio = maxOf(rawBlockerRatio);
+
+  const out = new Map<string, TriageResult>();
+  for (const b of beads) {
+    const pagerank_norm = safeDiv(rawPageRank.get(b.id) ?? 0, maxPageRank);
+    const betweenness_norm = safeDiv(
+      rawBetweenness.get(b.id) ?? 0,
+      maxBetweenness,
+    );
+    const blocker_ratio_norm = safeDiv(
+      rawBlockerRatio.get(b.id) ?? 0,
+      maxBlockerRatio,
+    );
+    const staleness_norm = stalenessNorm(b, now);
+    const priority_boost_norm = priorityBoostNorm(b);
+    const time_to_impact_norm = timeToImpactNorm(
+      depth.get(b.id) ?? 0,
+      estimateMinutes,
+    );
+    const urgency_norm = urgencyNorm(b, now);
+    const risk_norm = riskNorm(b, now, incoming, inDegree);
+
+    const pagerank = pagerank_norm * TRIAGE_WEIGHTS.pagerank;
+    const betweenness = betweenness_norm * TRIAGE_WEIGHTS.betweenness;
+    const blocker_ratio = blocker_ratio_norm * TRIAGE_WEIGHTS.blocker_ratio;
+    const staleness = staleness_norm * TRIAGE_WEIGHTS.staleness;
+    const priority_boost =
+      priority_boost_norm * TRIAGE_WEIGHTS.priority_boost;
+    const time_to_impact =
+      time_to_impact_norm * TRIAGE_WEIGHTS.time_to_impact;
+    const urgency = urgency_norm * TRIAGE_WEIGHTS.urgency;
+    const risk = risk_norm * TRIAGE_WEIGHTS.risk;
+
+    const score =
+      pagerank + betweenness + blocker_ratio + staleness +
+      priority_boost + time_to_impact + urgency + risk;
+
+    out.set(b.id, {
+      score,
+      breakdown: {
+        pagerank,
+        betweenness,
+        blocker_ratio,
+        staleness,
+        priority_boost,
+        time_to_impact,
+        urgency,
+        risk,
+        pagerank_norm,
+        betweenness_norm,
+        blocker_ratio_norm,
+        staleness_norm,
+        priority_boost_norm,
+        time_to_impact_norm,
+        urgency_norm,
+        risk_norm,
+      },
+    });
+  }
+  return out;
+}
+
+// ── signals ───────────────────────────────────────────────────────────────
+
+// ── graph indexing ────────────────────────────────────────────────────────
+//
+// Both graph signals ran over Map<string, …> keyed by bead id, with a plain
+// array as the BFS queue and queue.shift() as the dequeue — O(n) per shift.
+// On a 579-bead repo that was ~300ms in the browser (bp-67g.25), 90% of the
+// triage pipeline, all of it on the first drawer open. Indexing beads to
+// integers once and running both over typed arrays with a head-pointer queue
+// is the same arithmetic in the same order, so the results are unchanged to
+// the last bit; only the bookkeeping is cheaper.
+
+interface IndexedGraph {
+  n: number;
+  /** Compressed out-adjacency: out-neighbours of i are adj[outStart[i]..outStart[i+1]). */
+  outStart: Int32Array;
+  adj: Int32Array;
+}
+
+function indexGraph(beads: Bead[], outgoing: Map<string, string[]>): IndexedGraph {
+  const n = beads.length;
+  const index = new Map<string, number>();
+  beads.forEach((b, i) => index.set(b.id, i));
+  const outStart = new Int32Array(n + 1);
+  const adjList: number[] = [];
+  for (let i = 0; i < n; i++) {
+    outStart[i] = adjList.length;
+    for (const w of outgoing.get(beads[i].id) ?? []) {
+      const j = index.get(w);
+      if (j !== undefined) adjList.push(j);
+    }
+  }
+  outStart[n] = adjList.length;
+  return { n, outStart, adj: Int32Array.from(adjList) };
+}
+
+/**
+ * Standard PageRank with damping factor 0.85, iterated to convergence
+ * (tolerance 1e-6 or 1000 iterations). Edges point blocker → dependent so
+ * PR flows toward downstream work — high PR ≈ many things depend on this.
+ */
+function pageRank(
+  beads: Bead[],
+  outgoing: Map<string, string[]>,
+): Map<string, number> {
+  const { n, outStart, adj } = indexGraph(beads, outgoing);
+  const damping = 0.85;
+  const tol = 1e-6;
+  const base = (1 - damping) / Math.max(1, n);
+  let rank = new Float64Array(n).fill(1 / Math.max(1, n));
+  let next = new Float64Array(n);
+
+  for (let iter = 0; iter < 1000; iter++) {
+    next.fill(base);
+
+    // Dangling mass — the rank held by beads that block nothing — has to be
+    // redistributed, not dropped. This loop used to `continue` past those
+    // beads, which silently deleted their share every iteration: the rank
+    // vector stopped summing to 1 and drained toward whichever beads had
+    // incoming edges. On a bead graph that is most of the graph (a bead that
+    // blocks nothing is the normal case), so the leak was the dominant term
+    // and it changed the ORDERING, not just the scale — the one signal still
+    // disagreeing with bv after bp-67g.37's other fixes.
+    let dangling = 0;
+    for (let v = 0; v < n; v++) {
+      const start = outStart[v];
+      const end = outStart[v + 1];
+      if (end === start) {
+        dangling += rank[v];
+        continue;
+      }
+      const share = (damping * rank[v]) / (end - start);
+      for (let e = start; e < end; e++) next[adj[e]] += share;
+    }
+    if (dangling !== 0) {
+      const add = (damping * dangling) / Math.max(1, n);
+      for (let v = 0; v < n; v++) next[v] += add;
+    }
+
+    // L2, matching the tolerance's scale: an L1 sum over hundreds of beads
+    // hits a fixed tolerance much later than the values have settled.
+    let delta = 0;
+    for (let v = 0; v < n; v++) {
+      const d = next[v] - rank[v];
+      delta += d * d;
+    }
+    [rank, next] = [next, rank];
+    if (Math.sqrt(delta) < tol) break;
+  }
+  const out = new Map<string, number>();
+  beads.forEach((b, i) => out.set(b.id, rank[i]));
+  return out;
+}
+
+/**
+ * Betweenness centrality via Brandes' algorithm. O(V·E). Counts the number
+ * of shortest source→target paths (over all pairs) that pass through each
+ * node.
+ *
+ * A source with no outgoing edges starts no path, so its BFS would visit
+ * itself and contribute nothing; skipping it is exact, not an approximation,
+ * and on a bead graph — where most beads block nothing — it skips most of
+ * the work. Predecessor lists are kept as a linked list over one preallocated
+ * buffer (each edge is a predecessor edge at most once per source), so a
+ * source costs no allocation beyond the first.
+ */
+function betweennessCentrality(
+  beads: Bead[],
+  outgoing: Map<string, string[]>,
+): Map<string, number> {
+  const { n, outStart, adj } = indexGraph(beads, outgoing);
+  const m = adj.length;
+  const cb = new Float64Array(n);
+  const dist = new Int32Array(n);
+  const sigma = new Float64Array(n);
+  const delta = new Float64Array(n);
+  const stack = new Int32Array(n);
+  const queue = new Int32Array(n);
+  const predHead = new Int32Array(n);
+  const predNext = new Int32Array(Math.max(1, m));
+  const predNode = new Int32Array(Math.max(1, m));
+
+  for (let s = 0; s < n; s++) {
+    if (outStart[s + 1] === outStart[s]) continue;
+    dist.fill(-1);
+    sigma.fill(0);
+    delta.fill(0);
+    predHead.fill(-1);
+    let pc = 0;
+    let qHead = 0;
+    let qTail = 0;
+    let sp = 0;
+    dist[s] = 0;
+    sigma[s] = 1;
+    queue[qTail++] = s;
+    while (qHead < qTail) {
+      const v = queue[qHead++];
+      stack[sp++] = v;
+      const dv = dist[v];
+      for (let e = outStart[v]; e < outStart[v + 1]; e++) {
+        const w = adj[e];
+        if (dist[w] < 0) {
+          dist[w] = dv + 1;
+          queue[qTail++] = w;
+        }
+        if (dist[w] === dv + 1) {
+          sigma[w] += sigma[v];
+          predNode[pc] = v;
+          predNext[pc] = predHead[w];
+          predHead[w] = pc;
+          pc++;
+        }
+      }
+    }
+    while (sp > 0) {
+      const w = stack[--sp];
+      for (let p = predHead[w]; p !== -1; p = predNext[p]) {
+        const v = predNode[p];
+        delta[v] += (sigma[v] / sigma[w]) * (1 + delta[w]);
+      }
+      if (w !== s) cb[w] += delta[w];
+    }
+  }
+  const out = new Map<string, number>();
+  beads.forEach((b, i) => out.set(b.id, cb[i]));
+  return out;
+}
+
+/**
+ * Priority → 0..1 boost. P0 → 1.0, P4 → 0.0. Deferred beads get 0.
+ */
+function priorityBoostNorm(b: Bead): number {
+  if (b.status === "deferred") return 0;
+  const p = b.priority ?? 4;
+  return Math.max(0, (4 - p) / 4);
+}
+
+/**
+ * Days since a bead was last touched, against a fixed 30-day horizon.
+ *
+ * ABSOLUTE, not relative to the stalest bead in the repo. The relative
+ * version this replaces divided by the population maximum, which had two
+ * consequences and both were wrong: the stalest bead always scored 1.0
+ * however recently it was touched (in one captured fixture every bead had
+ * been updated within three hours and they all scored 0.93-1.00), and the
+ * number meant nothing outside its own repo.
+ *
+ * 30 days is bv's horizon and there is no reason to differ. A bead idle
+ * two weeks now reads 0.47, which is a statement about the bead rather
+ * than about its neighbours.
+ */
+function stalenessNorm(b: Bead, now: number): number {
+  if (!b.updated_at) return 0.5; // unknown — moderate rather than extreme
+  const days = (now - +new Date(b.updated_at)) / MS_PER_DAY;
+  if (!Number.isFinite(days)) return 0.5;
+  return clamp01(days / STALENESS_HORIZON_DAYS);
+}
+
+/**
+ * Time-to-impact — how quickly finishing this converts into downstream
+ * unblocks. Depth dominates because it is the structural part:
+ *
+ *   0.7 · (depth / 10) + 0.3 · (1 − minutes / 480)
+ *
+ * `depth` is the longest chain of blockers ending at this bead, so a bead
+ * deep in a chain releases more when it lands. The time factor rewards
+ * short work against an 8-hour day.
+ *
+ * This used to be the constant 0.2625, which was that formula evaluated at
+ * depth 0 with a 60-minute estimate — the value bv returns for a leaf. It
+ * was a constant here because we never computed depth, so a tenth of the
+ * declared weight bought exactly nothing. With depth wired up it spans
+ * 0.15-0.43 on a real 577-bead repo.
+ */
+function timeToImpactNorm(depth: number, estimateMinutes: number): number {
+  const depthNorm = clamp01(depth / MAX_CRITICAL_PATH_DEPTH);
+  const timeFactor = clamp01(1 - estimateMinutes / MINUTES_PER_WORKDAY);
+  return depthNorm * 0.7 + timeFactor * 0.3;
+}
+
+/**
+ * Urgency — declared urgency plus the pressure of an unresolved bead
+ * ageing. Label first, then a decay term that grows toward 0.5 with a
+ * 7-day half-life, capped at 1.0.
+ *
+ * Deliberately keyed on `created_at` (how long this has been outstanding)
+ * where staleness is keyed on `updated_at` (how long since anyone touched
+ * it). Two different questions; the previous implementation multiplied
+ * staleness by priority, which made urgency a function of the two signals
+ * either side of it and left it unable to reach past 0.5 on any repo.
+ */
+function urgencyNorm(b: Bead, now: number): number {
+  let score = 0;
+  for (const label of b.labels ?? []) {
+    const lower = label.toLowerCase();
+    const hit = URGENCY_LABELS.find((u) => lower.includes(u.match));
+    if (hit) {
+      score += hit.weight;
+      break;
+    }
+  }
+  if (b.created_at) {
+    const age = (now - +new Date(b.created_at)) / MS_PER_DAY;
+    if (Number.isFinite(age) && age > 0) {
+      score += 0.5 * (1 - Math.exp(-age / URGENCY_HALF_LIFE_DAYS));
+    }
+  }
+  return clamp01(score);
+}
+
+/**
+ * Risk — a composite of four volatility signals, weighted 0.30 / 0.30 /
+ * 0.20 / 0.20. Replaces a constant 0.02, which gave a tenth of the
+ * declared weight a reachable ceiling of 0.002 and two distinct values
+ * across an entire repo. The composite takes 89 distinct values over the
+ * same 215 open beads.
+ *
+ * cross-repo risk is absent rather than zero-weighted: every bead in a
+ * `bd` workspace is in one repo, so the term has nothing to measure. Its
+ * 0.20 is left unclaimed rather than redistributed, so a composite here is
+ * directly comparable with one that does have cross-repo edges.
+ */
+function riskNorm(
+  b: Bead,
+  now: number,
+  incoming: Map<string, string[]>,
+  inDegree: Map<string, number>,
+): number {
+  // A landed bead has no risk of not landing. status_risk already says 0
+  // here, but activity_churn does not look at status, so a busy bead would
+  // keep carrying risk after it closed. bv never hits this case — it drops
+  // closed issues before scoring — so the behaviour is ours to define, and
+  // zero is the only sensible answer. Deferred is deliberately NOT included:
+  // bv does score deferred beads, and a deferred bead genuinely is at risk.
+  if (b.status === "closed" || b.status === "tombstone") return 0;
+  return (
+    0.3 * fanVariance(b, incoming, inDegree) +
+    0.3 * activityChurn(b, now) +
+    0.2 * statusRisk(b, now)
+  );
+}
+
+/**
+ * How unevenly popular this bead's blockers are, as a coefficient of
+ * variation over their in-degrees, normalised against CV 2. Depending on
+ * one heavily-depended-on thing and one obscure thing is a riskier shape
+ * than depending on two similar things. Needs at least two blockers to
+ * mean anything.
+ */
+function fanVariance(
+  b: Bead,
+  incoming: Map<string, string[]>,
+  inDegree: Map<string, number>,
+): number {
+  const degrees = (incoming.get(b.id) ?? []).map((id) => inDegree.get(id) ?? 0);
+  if (degrees.length < 2) return 0;
+  const mean = degrees.reduce((a, d) => a + d, 0) / degrees.length;
+  if (mean === 0) return 0;
+  const variance =
+    degrees.reduce((a, d) => a + (d - mean) ** 2, 0) / degrees.length;
+  return clamp01(Math.sqrt(variance) / mean / 2);
+}
+
+/**
+ * Edit and comment traffic relative to age. A bead being argued over is
+ * less settled than one written once and left alone.
+ */
+function activityChurn(b: Bead, now: number): number {
+  if (!b.created_at) return 0;
+  const ageDays = Math.max(1, (now - +new Date(b.created_at)) / MS_PER_DAY);
+  if (!Number.isFinite(ageDays)) return 0;
+  const commentsPerDay = (b.comment_count ?? 0) / ageDays;
+  // How much of its life the bead has been touched over: a bead updated
+  // once at creation reads 0, one still being edited reads near 1.
+  let updateRecency = 0;
+  if (b.created_at && b.updated_at && ageDays > 1) {
+    const span = (+new Date(b.updated_at) - +new Date(b.created_at)) / MS_PER_DAY;
+    if (Number.isFinite(span) && span > 0) updateRecency = span / ageDays;
+  }
+  return clamp01(commentsPerDay * 0.6 + updateRecency * 0.4);
+}
+
+/**
+ * Risk carried by the status itself, and by how long the bead has sat in
+ * it. Blocked is the worst place to be, and blocked-and-untouched is worse.
+ * In-progress is only risky once it stops moving.
+ */
+function statusRisk(b: Bead, now: number): number {
+  const idleDays = b.updated_at
+    ? (now - +new Date(b.updated_at)) / MS_PER_DAY
+    : 0;
+  const ageDays = b.created_at
+    ? (now - +new Date(b.created_at)) / MS_PER_DAY
+    : 0;
+  switch (b.status) {
+    case "blocked":
+      return idleDays > 7 ? 0.9 : 0.7;
+    case "in_progress":
+    case "in_review":
+      if (idleDays > 14) return 0.8; // moving once, not any more
+      if (idleDays > 7) return 0.4;
+      return 0.1;
+    case "open":
+    case "pinned":
+      return ageDays > 30 ? 0.3 : 0.1;
+    default:
+      // closed, deferred, tombstoned — out of play, no risk to carry.
+      return 0;
+  }
+}
+
+/**
+ * Longest chain of work this bead RELEASES — the depth of live dependents
+ * below it. Finishing something at the head of a long chain unblocks more
+ * than finishing a leaf, which is what time_to_impact's depth term is for
+ * ("higher depth = more impact when completed").
+ *
+ * Two deliberate choices, both about meaning rather than range:
+ *
+ *  - DOWNSTREAM, not upstream. The chain of things waiting on you is the
+ *    impact of finishing; the chain of things you are waiting on is a
+ *    different fact, and `blocker_ratio` already carries a piece of it.
+ *  - CLOSED dependents are pruned. A dependent that is already closed was
+ *    not waiting on this bead, so counting it inflates the impact of
+ *    finishing. Pruning costs range — on a 577-bead repo it takes depth
+ *    from 5 distinct values to 3 — and is still right.
+ *
+ * A bead with no live blocking edges either way is not in the graph and
+ * scores 0, which is what separates "isolated" from "head of a chain".
+ *
+ * Iterative over a topological order rather than recursive, so a cycle in
+ * the dependency data cannot blow the stack; beads inside a cycle keep
+ * whatever height their acyclic ancestors gave them.
+ */
+function graphHeights(beads: Bead[], byId: Map<string, Bead>): Map<string, number> {
+  const isLive = (id: string) => byId.get(id)?.status !== "closed";
+  const down = new Map<string, string[]>(); // blocker -> things it releases
+  const up = new Map<string, string[]>();
+  for (const b of beads) {
+    down.set(b.id, []);
+    up.set(b.id, []);
+  }
+  for (const b of beads) {
+    if (!isLive(b.id)) continue; // a closed dependent was not waiting
+    for (const d of b.dependencies ?? []) {
+      if (d.type !== "blocks") continue;
+      if (!byId.has(d.depends_on_id)) continue;
+      down.get(d.depends_on_id)!.push(b.id);
+      up.get(b.id)!.push(d.depends_on_id);
+    }
+  }
+
+  const height = new Map<string, number>();
+  const pending = new Map<string, number>();
+  const queue: string[] = [];
+  for (const b of beads) {
+    const deg = up.get(b.id)!.length;
+    pending.set(b.id, deg);
+    const isolated = deg === 0 && down.get(b.id)!.length === 0;
+    height.set(b.id, isolated ? 0 : deg === 0 ? 1 : 0);
+    if (deg === 0) queue.push(b.id);
+  }
+  for (let i = 0; i < queue.length; i++) {
+    const id = queue[i];
+    for (const next of down.get(id) ?? []) {
+      height.set(next, Math.max(height.get(next) ?? 0, (height.get(id) ?? 0) + 1));
+      const left = (pending.get(next) ?? 0) - 1;
+      pending.set(next, left);
+      if (left === 0) queue.push(next);
+    }
+  }
+
+  // The queue walked blocker -> dependent, so `height` currently holds the
+  // chain ABOVE each node. Depth-below is the same walk from the other end:
+  // take the maximum height reachable downstream and subtract our own.
+  const reach = new Map<string, number>(height);
+  for (let i = queue.length - 1; i >= 0; i--) {
+    const id = queue[i];
+    for (const next of down.get(id) ?? []) {
+      reach.set(id, Math.max(reach.get(id) ?? 0, reach.get(next) ?? 0));
+    }
+  }
+  const below = new Map<string, number>();
+  for (const b of beads) {
+    const h = height.get(b.id) ?? 0;
+    below.set(b.id, h === 0 ? 0 : (reach.get(b.id) ?? h) - h);
+  }
+  return below;
+}
+
+// ── population statistics ─────────────────────────────────────────────────
+
+export interface SignalPopulation {
+  signal: TriageSignal;
+  /** Distinct values across the population, to 4dp. */
+  distinct: number;
+  stdev: number;
+  /** How many of the population have a non-zero value for this signal. */
+  nonzero: number;
+  max: number;
+  /** 90th percentile of the norm across the population. */
+  p90: number;
+  /**
+   * True when the signal cannot separate beads ON THIS REPO: three or fewer
+   * distinct values, or a spread small enough that it is a constant with
+   * rounding on it.
+   *
+   * Distinct from SIGNAL_FIDELITY, which is about whether we agree with bv.
+   * A signal can be perfectly faithful and still flat here — betweenness is
+   * non-zero on 1 of 216 open beads on a real 577-bead repo, so it carries
+   * the second-largest weight and separates nothing. That is a property of
+   * shallow dependency graphs, not a defect, but a reader comparing two
+   * beads deserves to know which axes are doing no work.
+   */
+  degenerate: boolean;
+}
+
+/**
+ * Per-signal spread across a set of beads — the denominator for "is this
+ * axis telling me anything". Cheap: one pass over an already-computed
+ * triage map, ~4ms for 216 beads.
+ */
+export function signalPopulation(
+  ids: Iterable<string>,
+  triage: Map<string, TriageResult>,
+): SignalPopulation[] {
+  const idList = [...ids];
+  return (Object.keys(TRIAGE_WEIGHTS) as TriageSignal[]).map((signal) => {
+    const vals: number[] = [];
+    for (const id of idList) {
+      const t = triage.get(id);
+      if (t) vals.push(t.breakdown[`${signal}_norm`]);
+    }
+    const n = Math.max(1, vals.length);
+    const mean = vals.reduce((a, x) => a + x, 0) / n;
+    const stdev = Math.sqrt(
+      vals.reduce((a, x) => a + (x - mean) ** 2, 0) / n,
+    );
+    const distinct = new Set(vals.map((v) => v.toFixed(4))).size;
+    const sorted = [...vals].sort((a, b) => a - b);
+    return {
+      signal,
+      distinct,
+      stdev,
+      nonzero: vals.filter((v) => v > 1e-9).length,
+      max: vals.length ? Math.max(...vals) : 0,
+      // What "high" looks like for this signal here. The absolute scales
+      // are meaningful but narrow in practice — nothing on a healthy repo
+      // is 30 days stale — so a bar read against the weight alone always
+      // looks empty. This is the comparative marker that makes it readable.
+      p90: sorted.length
+        ? sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.9))]
+        : 0,
+      degenerate: distinct <= 3 || stdev < 0.01,
+    };
+  });
+}
+
+// ── helpers ───────────────────────────────────────────────────────────────
+
+function maxOf(m: Map<string, number>): number {
+  let max = 0;
+  for (const v of m.values()) if (v > max) max = v;
+  return max;
+}
+
+function safeDiv(num: number, denom: number): number {
+  if (denom === 0) return 0;
+  return num / denom;
+}
+
+// ── score population ──────────────────────────────────────────────────────
+//
+// "18.1%" is unreadable without knowing what is typical, and the composite
+// score is severely right-skewed on a real repo (bp-67g.28: min 5.8%, median
+// 11.5%, max 36.7% over 216 open beads), so a bare percentage hides that
+// 18.1% is the top 7%. The drawer draws the population the score came from.
+//
+// OPEN beads only, by design: closed beads still carry a score, and
+// including them would put every live bead in the top decile of a mostly-
+// dead field. Cheap — ~0.4ms over the already-computed triage map on 579
+// beads — and read only from the drawer, so triage itself stays lazy.
+
+export interface ScorePopulation {
+  /** Composite scores of the population, ascending. */
+  scores: number[];
+  n: number;
+  min: number;
+  max: number;
+  /** Quartiles of `scores`: the value at the 25th, 50th and 75th percentile. */
+  p25: number;
+  p50: number;
+  p75: number;
+  /** Counts per equal-width bin across [min, max]. */
+  histogram: number[];
+}
+
+export function scorePopulation(
+  ids: readonly string[],
+  triage: Map<string, TriageResult>,
+  bins = 40,
+): ScorePopulation {
+  const scores: number[] = [];
+  for (const id of ids) {
+    const t = triage.get(id);
+    if (t) scores.push(t.score);
+  }
+  scores.sort((a, b) => a - b);
+  const n = scores.length;
+  const min = scores[0] ?? 0;
+  const max = scores[n - 1] ?? 0;
+  const span = max - min || 1;
+  const histogram = new Array<number>(bins).fill(0);
+  for (const s of scores) {
+    histogram[Math.min(bins - 1, Math.floor(((s - min) / span) * bins))]++;
+  }
+  const at = (p: number) => (n ? scores[Math.min(n - 1, Math.floor(p * n))] : 0);
+  return { scores, n, min, max, p25: at(0.25), p50: at(0.5), p75: at(0.75), histogram };
+}
+
+/** Share of the population scoring at or below `score`, 0..1. */
+export function percentileOf(pop: ScorePopulation, score: number): number {
+  const { scores } = pop;
+  if (!scores.length) return 0;
+  let lo = 0;
+  let hi = scores.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (scores[mid] <= score) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo / scores.length;
+}
+
+/**
+ * The percentile as a reader says it: "top 7% of 216 open beads". Always the
+ * top-N form, so a median bead reads "top 50%" rather than switching vocabulary
+ * halfway down the distribution; never below "top 1%".
+ */
+export function describeRank(pop: ScorePopulation, score: number): string {
+  if (!pop.n) return "no open beads to compare against";
+  const above = Math.max(1, Math.round((1 - percentileOf(pop, score)) * 100));
+  return `top ${above}% of ${pop.n} open bead${pop.n === 1 ? "" : "s"}`;
+}