feat(routing): implement dijkstra shortest path

[404khai]

Summary

Implements Phase 5 of the Roadrunner roadmap with a manual Dijkstra shortest-path baseline in roadrunner-core.

• uses BinaryHeap for the frontier
• tracks best-known costs and predecessor edges with HashMap
• reconstructs and validates the ordered node/edge path
• returns total physical distance, selected route cost, algorithm identity, and finalized-node count
• supports any CostModel, including distance and travel-time objectives
• adds typed endpoint, no-route, cost, graph, accumulation, and reconstruction failures
• adds deterministic routing tests and a 1K/10K/100K benchmark
• records the initial benchmark as structured JSON with reproducibility metadata

Correctness and determinism

The implementation validates both endpoints before searching and rejects cost values whose kind differs from the model's advertised kind.

Equal-cost queue entries prefer the lower NodeId. Outgoing edges are evaluated in (destination NodeId, EdgeId) order, so path selection does not depend on HashMap iteration or edge insertion order. Relaxation accepts only strictly lower costs, preventing equal-cost and zero-cost cycles from rewriting predecessor chains.

Route reconstruction verifies that every predecessor edge still exists and reaches the expected node. Distance and route-cost accumulation revalidate floating-point results so overflow is reported rather than propagated.

Route result

RouteResult exposes:

• ordered node path
• ordered directed edge IDs
• total physical distance
• total selected cost and cost kind
• algorithm (dijkstra)
• finalized/visited node count

A source equal to its destination returns one node, zero edges, zero distance/cost, and one finalized node.

Tests

New algorithm tests cover:

• a graph with a known optimal path
• source equal to destination
• unreachable destinations and disconnected graphs
• unknown source and destination nodes
• zero-cost cycles
• distance-cost versus travel-time route selection
• parallel-edge selection
• equal-cost determinism across reversed insertion order
• mismatched custom cost-model output

The complete workspace suite contains 43 passing tests.

Benchmark

crates/roadrunner-core/benches/dijkstra.rs generates deterministic directed ring-lattice graphs with fan-out 3 and runs distance-cost searches from node 0 to the final node. Graph construction is outside the timed closure.

Initial Apple M3 results from 20 Criterion samples per case:

Nodes	Edges	Visited	Median	p95	p99
1,000	3,000	1,000	0.303 ms	0.316 ms	0.326 ms
10,000	30,000	10,000	3.121 ms	4.207 ms	4.272 ms
100,000	300,000	100,000	55.346 ms	57.799 ms	58.080 ms

The complete hardware, software, dataset, configuration, iteration counts, percentile method, and raw nanosecond summaries are recorded in benchmarks/results/2026-09-02-apple-m3-dijkstra.json.

Memory is explicitly recorded as unavailable because the repository does not yet have a controlled allocator or profiler configuration. No cross-machine performance claim is made.

Validation

• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
• cargo test --workspace --all-features --locked
• cargo bench --workspace --no-run --locked
• cargo bench -p roadrunner-core --bench dijkstra --locked
• RUSTDOCFLAGS=-Dwarnings cargo doc --workspace --no-deps --locked
• benchmark JSON and Markdown-link validation
• git diff --check main...HEAD