59845f4059
Docker realization (bridging simulation to real TCP): - NodeDriver (`crates/distribution/src/driver.rs`): bridges DistributedNode tick loop to TcpTransport with piggyback-extended wire messages - swactor-node binary (`crates/node/`): CLI node with --listen, --seed, --dashboard-port, --actors flags - Dockerfile: multi-stage build (rust:1.93-slim → debian:bookworm-slim) - Docker integration tests (`tests/docker/`): 5-node cluster with 4 scenarios (convergence, failure detection, actor resolution, rejoin) - LAN cluster scripts for cross-machine validation - TCP transport retry-on-stale-connection logic - /api/distribution REST endpoint on dashboard (feature-gated) - Piggyback fields (piggyback + from_addr) on Ping/Ack/PingReq messages Docs reorganization: - docs/runtime/ — actor-model, runtime, worker-thread, channels - docs/distribution/ — distribution, swim, kademlia, transport - docs/diagrams/ — all SVG files - docs/connectome/ — connectome analysis - docs/development_history/ — DOCKER_REALIZATION.md, SIMULATION_TESTING.md - render_docs.sh outputs to docs/diagrams/ - README links updated to new paths Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
76 lines
2.8 KiB
Markdown
76 lines
2.8 KiB
Markdown
# Connectome Analysis
|
|
|
|
The connectome analysis applies spectral graph theory to the codebase's internal dependency DAG, producing quantitative coupling metrics and visual dashboards.
|
|
|
|
## What it measures
|
|
|
|
The tool parses `deps.dot` (a GraphViz DOT file describing struct/trait dependencies between modules) and computes:
|
|
|
|
- **Laplacian eigenvalue spectrum** -- encodes the graph's overall connectivity structure
|
|
- **Fiedler vector** -- the optimal spectral bisection of the dependency graph, revealing natural module clusters
|
|
- **Module coupling matrix** -- directed edge counts between every pair of modules
|
|
- **Connectome Complexity Index (CCI)** -- a single 0-1 score combining five sub-metrics:
|
|
|
|
| Sub-metric | Weight | What it captures |
|
|
|---|---|---|
|
|
| Algebraic connectivity (lambda_2/n) | 25% | How tightly connected the graph is |
|
|
| Spectral entropy (H/log2(k)) | 25% | How uniformly distributed coupling is across eigenvalues |
|
|
| Edge density (\|E\|/n(n-1)) | 15% | Raw ratio of edges to possible edges |
|
|
| Cross-module coupling ratio | 20% | Fraction of edges that cross module boundaries |
|
|
| Spectral radius (rho/(n-1)) | 15% | Maximum hub concentration |
|
|
|
|
### Interpreting CCI
|
|
|
|
| CCI range | Label | Meaning |
|
|
|---|---|---|
|
|
| < 0.30 | LOW | Well-decomposed architecture |
|
|
| 0.30 - 0.60 | MODERATE | Typical well-structured codebase |
|
|
| > 0.60 | HIGH | Consider reviewing module boundaries |
|
|
|
|
## Running
|
|
|
|
From the project root:
|
|
|
|
```sh
|
|
# Default: outputs to docs/connectome/
|
|
python tools/spectral/spectral_analysis.py deps.dot
|
|
|
|
# Custom output directory
|
|
python tools/spectral/spectral_analysis.py deps.dot -o path/to/output
|
|
|
|
# Also emit JSON metrics
|
|
python tools/spectral/spectral_analysis.py deps.dot --json
|
|
|
|
# Text report only (skip matplotlib PNG)
|
|
python tools/spectral/spectral_analysis.py deps.dot --no-plots
|
|
```
|
|
|
|
### Prerequisites
|
|
|
|
The script requires numpy, scipy, and matplotlib (for the PNG dashboard). These are available in the project's `.venv`:
|
|
|
|
```sh
|
|
source .venv/bin/activate
|
|
python tools/spectral/spectral_analysis.py deps.dot
|
|
```
|
|
|
|
## Output files
|
|
|
|
All output goes to `docs/connectome/` by default:
|
|
|
|
| File | Description |
|
|
|---|---|
|
|
| `connectome_report.txt` | Full text report with eigenvalues, Fiedler bisection, coupling matrix, and CCI breakdown |
|
|
| `connectome_dashboard.html` | Interactive HTML dashboard with zoomable DAG, eigenvalue plot, Fiedler bar chart, and coupling heatmap |
|
|
| `connectome_dashboard.png` | Static PNG snapshot of the spectral dashboard (dark theme, 16x12 @ 150 DPI) |
|
|
| `connectome_metrics.json` | Machine-readable metrics (only with `--json` flag) |
|
|
|
|
## Regenerating deps.dot
|
|
|
|
The DOT file is the input to the spectral analysis. To regenerate it from source:
|
|
|
|
```sh
|
|
cargo run --manifest-path tools/depgraph/Cargo.toml -- --src-dir src/ --output deps
|
|
```
|
|
|
|
Then re-run the spectral analysis to update the connectome report.
|