feat(sim): add multi-seed fairness benchmark and empirical research notes

[Yudis-bit]

Summary

• Added simulation/simulations/benchmark_multi_seed.py evaluating seeds [42, 100, 777, 1337, 2026]
• Added simulation/RESEARCH_NOTES.md detailing cycle-loop mechanics in mesh networks and multi-seed sensitivity
• Updated README.md with transparent multi-seed results and links to research notes

Verification

• python -m pytest simulation/tests: 6 smoke tests pass
• benchmark_multi_seed.py verified across 1,000 packets/seed

[Copilot]

🟡 Changes recommended

Resolve the hop-limit inconsistency, congestion metric accounting/reporting, and incorrect README command.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a multi-seed routing fairness benchmark, empirical research notes, and README documentation.

Changes:

• Added five-seed evaluation across 1,000 packets per seed.
• Documented routing loops, trade-offs, and observed results.
• Updated README with benchmark links and reproduction instructions.

File summaries

File	Description
simulation/simulations/benchmark_multi_seed.py	Implements multi-seed routing evaluation.
simulation/RESEARCH_NOTES.md	Documents empirical results and routing mechanics.
README.md	Links to the benchmark and research notes.

Review details

Suppressed comments (5)

README.md:17

• This command is documented as if run from the repository root, but simulations/benchmark_multi_seed.py does not exist there; the added script is under simulation/simulations/. Following this instruction from the root fails with FileNotFoundError. Use python simulation/simulations/benchmark_multi_seed.py (or explicitly document changing into simulation/).

* **Multi-Seed Evaluation & Mechanics:** See [`simulation/RESEARCH_NOTES.md`](simulation/RESEARCH_NOTES.md) for a multi-seed analysis (seeds 42, 100, 777, 1337, 2026) explaining the trade-offs between local link-reward exploration and multi-hop loop traps. Run `python simulations/benchmark_multi_seed.py` to reproduce the multi-seed evaluation matrix.

simulation/RESEARCH_NOTES.md:25

• The notes say packets are dropped after exhausting MAX_HOPS = 25, but both the benchmark and the existing simulation guard with if hops > MAX_HOPS, so a packet can make 26 hops before it is marked failed. Please describe the actual boundary (or change the benchmark guard to >= and keep it consistent with the simulator) so the documented loop behavior is reproducible.

   - Once trapped in a cyclic subgraph, packets traverse links repeatedly until exhausting `MAX_HOPS = 25`, after which the packet is dropped as failed.

simulation/simulations/benchmark_multi_seed.py:83

• cog_cong is incremented only for successful packets, but cog_cong_rate divides by num_packets (and is intended to be comparable with the Dijkstra per-packet rate). As a result, every failed packet is implicitly treated as non-congested, so this returned metric understates congestion whenever a failed route encountered the congested link. Count congestion for every attempted packet (outside the if succ block), or explicitly divide by cog_succ and label it as a successful-delivery-only metric.

        if succ:
            cog_succ += 1
            cog_total_lat += plat
            if is_cong:
                cog_cong += 1

    cog_deliv_rate = (cog_succ / num_packets) * 100.0
    cog_avg_lat = (cog_total_lat / cog_succ) if cog_succ > 0 else float('nan')
    cog_cong_rate = (cog_cong / num_packets) * 100.0

simulation/simulations/benchmark_multi_seed.py:103

• cog_cong_rate is computed but neither the table nor the research output reports it; the benchmark therefore does not expose the cognitive congestion result despite claiming to evaluate congestion across seeds. Add a CRP congestion column/value to the printed matrix (and keep the notes table in sync) so the reported results are reproducible and auditable.

    print(f"{'Seed':>5} | {'Dijkstra Lat':>12} | {'Dijkstra Cong':>13} | {'CRP Deliv %':>11} | {'CRP Loss %':>10} | {'CRP Lat':>9} | {'Lat Gain %':>10}")

simulation/simulations/benchmark_multi_seed.py:21

• This new benchmark path is not covered by the existing simulation smoke suite, so regressions in seed isolation, delivery/loss accounting, or the reported matrix can pass while the documented multi-seed results become stale. Add a focused test using a small num_packets value that exercises evaluate_seed and asserts its returned metrics, or a captured-output smoke test for main.

def evaluate_seed(seed: int, num_packets: int = 1000):

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.