feat(network): Network Calculus primitives — arrival/service curves + min-plus ops (Track D commit 3/6)

[avrabe]

Summary

Track D commit 3 of 6 for v0.8.0. Adds the pure-math Network Calculus
kernel that the upcoming wctt.rs analysis pass (commit 4) will
compose. No analysis pass, no Lean theorems, no latency.rs integration
yet — those are commits 4, 5, and 6.

New module crates/spar-network/src/curves.rs:

• ArrivalCurve — leaky-bucket affine σ + ρ·t with optional peak cap.
• ServiceCurve — rate-latency R · max(0, t − T).
• backlog_bound(α, β) — closed-form σ + ρ·T (returns NcError::UnstableServer when ρ > R).
• delay_bound(α, β) — closed-form T + σ/R horizontal distance.
• residual_service(β, α_c) — FIFO residual: rate R − ρ_c, latency T + σ_c/(R − ρ_c).
• output_bound(α, β) — burst inflation theorem: σ' = σ + ρ·T, ρ' = ρ.

All values are u64 picoseconds / bytes / bits-per-second so the kernel
is free of f64 drift. Internal arithmetic widens to u128 for the
rate × time products to avoid overflow on realistic inputs (e.g. 100
Gbps × 1 ms ≈ 10⁸ bytes). Truncation rounds bytes-served down and
durations up, keeping the WCTT consumer on the safe side of every
bound.

References Le Boudec & Thiran "Network Calculus" §1.4 (the closed-form
bounds for the affine + rate-latency case) per the design doc
docs/designs/track-d-tsn-wctt-research.md §4.3-4.4.

Out of scope for this commit (per the design doc): piecewise-affine
curves, TSN-specific service curves (TAS/Qbv, Qbu, Qcr ATS), PBOO
concatenation, and any AADL coupling — curves.rs deliberately does
not consume from extract.rs.

New requirement: REQ-NETWORK-005. New verification: TEST-NC-CURVES.

Test plan

• cargo build -p spar-network clean
• cargo test -p spar-network — 14 curves tests + 12 prior tests + 6 integration tests, all green
• cargo clippy --workspace --all-targets -- -D warnings clean
• cargo fmt --all -- --check clean
• rivet validate PASS (only the pre-existing schema-warning baseline)

Tests added (14)

#	Test	What it pins down
1	arrival_curve_at_zero_is_burst	α(0) = σ, with and without peak cap
2	service_curve_at_latency_is_zero	β(t ≤ T) = 0
3	service_curve_above_latency_grows_linearly	β(T + δ) = R · δ
4	affine_arrival_eval	α(t) = σ + ρ·t at 1 ms
5	affine_arrival_with_peak	Peak cap dominates for small t, sustained for large t
6	backlog_bound_classical	σ=1500, ρ=100 Mbps, T=10 µs → 1625 bytes
7	backlog_bound_unstable_when_rate_exceeds_service	ρ > R → NcError::UnstableServer
8	delay_bound_classical	Same params → T + σ/R = 22 µs
9	delay_bound_unstable_when_rate_exceeds_service	ρ > R → error
10	residual_service_two_flows	Two 400 Mbps flows on 1 Gbps server → 600 Mbps each, latency inflation 20 µs
11	residual_service_unservable	ρ_c ≥ R → NcError::UnservableFlow
12	output_bound_burst_inflation	Output burst grows by ρ·T
13	output_bound_rate_preserved	Sustained and peak rates pass through unchanged
14	compose_two_servers_classical	Two-hop naive composition: 22 µs + 18 µs = 40 µs

🤖 Generated with Claude Code

[temper-pulseengine]

AI Code Review for PR #161

pulseengine/spar:feat/v0.8.0-track-d-commit3-nc-primitives → pulseengine/spar:main

Summary

This pull request introduces a new module crates/spar-network/src/curves.rs that provides the Network Calculus primitives for arrival and service curves, along with four closed-form min-plus operators. The changes include:

1. New Module crates/spar-network/src/curves.rs:

   • ArrivalCurve: Represents a leaky-bucket affine curve with optional peak cap.
   • ServiceCurve: Represents a rate-latency service curve.
   • Functions to calculate:
     • backlog_bound(α, β): Closed-form backlog bound for the affine + rate-latency case.
     • delay_bound(α, β): Closed-form delay bound.
     • residual_service(β, α_c): Calculates FIFO residual service.
     • output_bound(α, β): Burst inflation theorem.

2. Updated Dependencies:

   • Added a new requirement REQ-NETWORK-005 to track the Network Calculus primitives and operators.
   • Created a verification test TEST-NC-CURVES to ensure the correctness of the curve and operator implementations.

3. Code Changes:

   • Updated the lib.rs file to include the new module and requirements/verification tests.
   • Modified requirements.yaml and verification.yaml to reflect these changes.

Potential Bugs or Issues

1. Overflow Handling:

   • The use of u64 for picoseconds, bytes, and bits per second ensures that calculations do not overflow on realistic inputs (e.g., 100 Gbps × 1 ms ≈ 10⁸ bytes). However, there is no explicit overflow checking in the code. This could be a potential issue if very large values are used.

2. Precision Loss:

   • The use of u64 for picoseconds and bytes means that precision may be lost when dealing with extremely small or large numbers. This should not affect typical network calculations, but it is worth noting.

3. Edge Cases:

   • The implementation does not handle edge cases such as zero rates, infinite rates, or negative times, which could lead to undefined behavior.

4. Security Concerns:

   • There are no security concerns related to the code itself, as it deals with mathematical calculations and does not involve any sensitive data.

Security Concerns

None identified.

Suggestions for Improvement

1. Overflow Checking:

   • Consider adding overflow checking in critical parts of the code to ensure that inputs do not exceed the range of u64.

2. Edge Case Handling:

   • Implement edge case handling for zero rates, infinite rates, and negative times to avoid undefined behavior.

3. Documentation:

   • Add more detailed documentation to explain the assumptions and limitations of the Network Calculus primitives and operators.

Overall Assessment

The pull request introduces a robust implementation of Network Calculus primitives that are essential for the WCTT analysis pass. The code is well-structured, with clear separation of concerns between the extract module and the curves module. The addition of requirements and verification tests ensures that the implementation meets the specified design goals. However, there are some potential areas for improvement related to overflow handling and edge case management. Overall, this is a significant contribution to the project and should be merged as soon as possible.

---

This review was generated by a local AI model. It is advisory only and may contain inaccuracies.

Reviewed at 562652a

[codecov]

Codecov Report

❌ Patch coverage is 94.68599% with 11 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
crates/spar-network/src/curves.rs	94.68%	11 Missing ⚠️

📢 Thoughts on this report? Let us know!