Module centrality 

Centrality analysis on the behavioural coupling graph.

Promotes the SoC-style coupling_centrality_v1 primitive (a bare COUNT(*) of Fisher-significant partners, materialised in code_health::run_code_health) to a first-class analysis with four per-file scores:

• degree: count of Fisher-significant coupling partners (the primitive code_health already used; kept as the network-science baseline so the new analysis subsumes the old behaviour).
• weighted-degree: sum of edge degree weights (the 100 * shared / average_revs ratio from CouplingRow) over all Fisher-significant partners. Captures “this file is coupled to N partners strongly”, not just “to N partners”.
• pagerank: power-iteration PageRank with damping 0.85, weighted by the same edge degrees. Captures “this file is coupled to other well-coupled files” — the recursive influence signal.
• eigenvector: power-iteration eigenvector centrality, also weighted. Same family as PageRank but no damping factor — converges faster on the connected component and complements PageRank’s bias toward dangling nodes.

All four are computed in one pass on a hash-adjacency representation (no petgraph graph construction overhead — the coupling graph is sparse, edges already de-duplicated by (entity_a, entity_b) lexicographic ordering).

Why these four

Skipped: betweenness (O(V·E) via Brandes — ~3.5B ops on a linux-kernel-scale 70k-node coupling graph), closeness (O(V³) — infeasible). PageRank + eigenvector together cover the “influence in a recursive-trust sense” axis that betweenness approximates more expensively.

Power iteration is the chosen numeric kernel for both PageRank and eigenvector centrality because:

1. It needs no external linear-algebra crate (no nalgebra / ndarray-linalg transitive bloat — both pull in BLAS-shaped dep trees for a single matrix-vector multiply).
2. The coupling graph’s spectral gap is large in practice (~10-15 iterations to converge to 1e-6 on the codelore-self ~600-edge graph; ~30 on the linux-kernel-scale one).
3. The graph is undirected so the dominant eigenvector is guaranteed positive (Perron-Frobenius), no sign-flip handling.

Research basis

• Degree centrality: classical network-analysis primitive (see e.g. Newman 2010 §7.1).
• Weighted degree: same primitive over the change-coupling weight space; CodeLore-specific instantiation.
• PageRank: Brin & Page 1998. Damping 0.85 is the canonical default.
• Eigenvector centrality: Bonacich 1972.

See docs/research-foundations.md entry “centrality” for the grounded write-up.

Structs

CentralityRow

One row per file appearing in at least one Fisher-significant coupling pair. Files with zero coupling partners are omitted (degree 0 across every variant — would just be noise).

Functions

compute_centrality

Pure-function core of run_centrality: takes coupling pairs + returns per-file centrality scores. Split out for direct unit-test access without needing a FactsDb.

from_coupling_pairs

Convenience: rebuild centrality directly from a CouplingRow slice for in-memory orchestration (e.g. code_health consumes the same pairs to compute coupling centrality alongside its other inputs; without this helper it would either pay a double-run_coupling cost or carry SQL-side state). The error path is unreachable on the in-memory branch — the trait signature keeps callers honest.

run_centrality

Compute the four centrality scores per file on the Fisher-significant coupling graph.