feat(scheduler): bandwidth model constants — realistic ECP5 + 8b/10b ceilings (closes #14)

[marcos-mendez]

Summary

Codifies the corrected rev-A bandwidth ceilings in the Spanker
scheduler so its capacity-planning logic uses real numbers, not the
stale ADR-001 "DDR3-1600 = 12.8 GB/s" theoretical claim that Stays
PR #26 (merged 2026-05-06) invalidated for the open ECP5 toolchain.

Adds a new module src/scheduler/src/bandwidth.rs with two
pub const u64 values, re-exported at the crate root:

pub const LOCAL_DDR_BW_BYTES_PER_SEC: u64 = 2_000_000_000; // 2.0 GB/s
pub const INTERCARD_BW_BYTES_PER_SEC: u64 =   500_000_000; // 500 MB/s per direction

LOCAL_DDR_BW is the midpoint of the 1.5–2.4 GB/s realistic range
observed across the three production references that drive
ECP5DDRPHY on the open toolchain (OrangeCrab, Trellis Board,
Versa-ECP5). INTERCARD_BW is the 4 lanes × 1.25 Gbps × 8b/10b ≈
500 MB/s number from InnerJib7EA pinout §9 (current 8b/10b baseline;
becomes ~600 MB/s when ADR-014 selects 64b/66b — bump in lockstep
with the ADR PR).

Source-of-truth references

• LOCAL_DDR_BW: Stays
  docs/upstream-contributions/2026-05-06-litedram-ecp5.md
  §Bandwidth budget (Stays PR #26, merged 2026-05-06).
• INTERCARD_BW: InnerJib7EA
  docs/hw/intercard-connector-pinout.md
  §9 (InnerJib7EA PR chore(scheduler): doc-only sentinel tests + closure-based all_reduce dispatch + comment ordering #11 corrected to 500 MB/s).
• Cross-stream amendment: MAST issue #32 — ADR-001 bandwidth
  amendment (Stream 1 in flight).

Did I find / replace any stale 12.8 or 12_800_000_000?

No. Repo-wide grep for 12.8, 12_800, LOCAL_DDR_BW, and
BW_BYTES_PER_SEC across *.rs, *.toml, and *.md (excluding
target/, .git/, .claude/worktrees/, external/) returned zero
hits in source. The stale value was a doc-claim in MAST ADR-001 only;
no Rust constant existed yet to replace. This PR is the load-bearing
constant the scheduler's future TP-vs-MP cost model will consume.

Why constants-only (no TP/MP decision logic)?

Per the issue triage and feedback_solo_mode_and_pr_workflow.md
scoping discipline: PRs #6 / #10 / #13 are scheduler scaffolding;
there is no live TP/MP decision logic to retrofit yet. The constants
are the load-bearing artefact for the next PR (downstream cost
model). Building the cost model on top of these constants is filed
as a separate scoped follow-up. Bench-harness validation against
measured throughput on first hardware bring-up is also a separate PR.

Tests

15 unit tests pass (5 new in bandwidth::tests + 10 pre-existing),
9 integration tests pass, 3 doc-tests pass:

• local_ddr_bw_is_not_the_stale_12_8_gb_per_sec_value — regression
  guard against accidental revert; asserts LOCAL_DDR_BW < 4 GB/s
  envelope (rejects both 6.4 and 12.8 GB/s; allows honest rev-B bump).
• local_ddr_bw_is_inside_observed_range — pins to the 1.5–2.4 GB/s
  band reported by Stays recon.
• intercard_bw_matches_innerjib7ea_pinout_section_9 — pins
  INTERCARD_BW to the doc-stated 500 MB/s.
• local_ddr_dominates_intercard_by_at_least_4x — LOCAL_DDR_BW >= 4 × INTERCARD_BW (rev-A lands at exactly 4× with the spec values;
  uses >= so the rev-A baseline passes; failure forces a TP/MP
  heuristic re-derivation conversation).
• constants_are_positive — rules out divide-by-zero in
  throughput-divided cost estimates.
• Crate-level doc-test in lib.rs shows intended usage:

  use spanker_scheduler::{LOCAL_DDR_BW_BYTES_PER_SEC, INTERCARD_BW_BYTES_PER_SEC};
  assert!(LOCAL_DDR_BW_BYTES_PER_SEC > INTERCARD_BW_BYTES_PER_SEC);

Implementation note: clippy assertions_on_constants

Const-vs-literal asserts in #[cfg(test)] would normally trip
clippy::assertions_on_constants. The test module gates the lint
with #![allow(clippy::assertions_on_constants)] because the intent
of every test is exactly that — pin a specific u64 constant against
a specific literal envelope. Refactoring through core::hint::black_box
would obscure intent without changing behaviour.

Test plan

• cargo build --workspace
• cargo test -p spanker-scheduler (15 unit + 9 integration + 3 doc-tests = 27)
• cargo clippy --workspace --all-targets -- -D warnings
• cargo fmt --all -- --check
• Pushed to github (https://github.com/popsolutions/Spanker)
• Pushed to origin (Forgejo, https://git.pop.coop/pop/Spanker)

Out of scope

• Building the TP/MP decision logic on top of these constants
  (separate scoped PR).
• Modifying ADR-001 — that's MAST #32 (Stream 1).
• Bench-harness validation against measured throughput on first
  hardware bring-up (separate PR).

Refs

• Closes [scheduler] Bandwidth model: correct DDR3-on-ECP5 ceiling from 12.8 GB/s (ADR-001 stale) to 1.5-2.4 GB/s #14
• Cross-stream: MAST #32 (ADR-001 amendment)
• Cross-stream: InnerJib7EA PR chore(scheduler): doc-only sentinel tests + closure-based all_reduce dispatch + comment ordering #11 (intercard pinout §9)
• Cross-stream: Stays PR #26 (LiteDRAM ECP5 recon, merged 2026-05-06)

Authored by Agent 3 (Software Stack — Spanker).

[marcos-mendez]

Review by Agent R

Verdict: APPROVE
Severity counts: CRITICAL=0 HIGH=0 MEDIUM=0 LOW=0

Pre-review gates (61198e7e)

• CI: 3/3 SUCCESS (Docs/SPDX, Driver/kbuild, Runtime/cargo)
• Mergeable: yes
• DCO sign-off + SPDX preserved
• 186+/0- across 2 files (1 new bandwidth.rs, 1 modified lib.rs)

Local verification (Agent R)

• cargo test -p spanker-scheduler --all-targets: 27/27 pass (15 unit including 5 new in bandwidth::tests, 9 integration, 3 doc-tests)
• cargo clippy --workspace --all-targets -- -D warnings: clean
• cargo fmt --check --all: clean

Test names auto-document the contract (excellent)

• intercard_bw_matches_innerjib7ea_pinout_section_9 → cross-reference encoded in test name; future doc drift between InnerJib7EA and Spanker triggers this assertion
• local_ddr_bw_is_not_the_stale_12_8_gb_per_sec_value → regression guard against accidental revert to ADR-001's pre-amendment number
• local_ddr_bw_is_inside_observed_range → asserts the constant sits inside the recon-evidenced 1.5-2.4 GB/s envelope
• local_ddr_dominates_intercard_by_at_least_4x → captures the TP-vs-MP heuristic threshold (uses >= correctly — Agent 3 caught my brief's bug where > would have failed at 2 GB/s vs 4×500 MB/s)
• constants_are_positive → trivial sanity guard

Cross-stream cross-checks verified by Agent 3

• MAST issue #32 (ADR-001 amendment, in flight as Stays PR #28) cited in module docstring + test comment
• InnerJib7EA pinout §9 (500 MB/s per direction, 8b/10b) — value matches INTERCARD_BW = 500_000_000
• Stays LiteDRAM recon (1.5–2.4 GB/s realistic) — midpoint 2.0 GB/s matches LOCAL_DDR_BW = 2_000_000_000
• 64b/66b → ~600 MB/s bump target documented in module docstring for when ADR-014 lands

Implementation note (good engineering judgment)

Agent 3 used >= instead of > in the 4x-dominance test because at the supplied constants 2e9 == 4×500e6 exactly. The brief's > would have falsely failed. Spirit of the guard preserved. Documented in test docstring + PR body. Approving the deviation.

No stale value found

Repo-wide grep across *.rs/*.toml/*.md (excluding target/git/external/worktrees) returned zero hits for 12.8 or 12_800_000_000. The stale value lived only in MAST ADR-001's doc claim — currently being amended in Stays PR #28 (R-approved, awaiting Marcos sign-off). This PR is the load-bearing constant the future TP/MP cost model will consume.

Action

Merging via two-step. Forgejo sync follows. The bandwidth correction loop is now closed end-to-end across all three streams (recon doc → ADR amendment proposed → scheduler constant codified).

Authored by Agent R (Reviewer).