refactor(platform): migrate device consumers to neutral facade

[zackees]

Phase 8a of the platform-boundary migration (#1314): removes all remaining device-namespace rows from the boundary ledger by moving every per-OS device mechanic still living in consumer crates behind fbuild_core::platform.

Ledger: 57 → 33 data rows (all 24 device rows gone; what remains is fs/ipc/host/process/host_executable for later phases). Research TSV and dylint baseline regenerated; the pinned-count test now asserts 33.

Changes

• SerialPortFacts.location_information — new fact carrying Windows SPDRP_LOCATION_INFORMATION (e.g. Port_#0003.Hub_#0004), populated by the SetupAPI enumeration, None elsewhere. Topology diagnostics survive the seam without leaking host mechanics.
• New platform::device::mount_block_devices — the udisksctl loop moves from rp2040_mount.rs into the Linux selected tree; Windows/macOS are honest no-ops. The RP-series ROM mount path calls the facade and keeps its scan/policy.
• New per-OS selected::host tree + platform::host::home_dir — %USERPROFILE% with %HOME% fallback on Windows, $HOME elsewhere, returned as NormalizedPath like the other neutral facades. lpc.rs, probe_rs.rs, and lpc_debugger_reflash.rs drop their three local env-var forks (one of which lacked the HOME fallback).
• rp2040_topology.rs rebuilt on facade facts — the hand-rolled setupapi/advapi32/cfgmgr32 FFI fork (~250 lines) is deleted; pure string classification (HubDepth, composite-CDC skipping) is now unconditional and tested on every host. Two deliberate deltas: phantom ports (fbuild port scan misses all PJRC/Teensy (VID 16C0) serial ports + no vendor/product resolution for them #962) get topology lines like live ones — better failure diagnostics — and endpoints with neither an instance ID nor ancestry return None instead of a flat "unavailable" sentence.
• rp2040_mount.rs / ports.rs de-cfg'd — candidate discovery is pure and runs everywhere; sysfs health enrichment self-noops wherever live_sysfs_usb_root() is None, replacing the #[cfg(target_os)] re-binding block. Stale doc notes about items "not existing cross-host" fixed.

Verification

• soldr cargo clippy --workspace --all-targets -- -D warnings exit 0
• Full bash test (unit + stress + integration) exit 0
• RUSTDOCFLAGS="-D warnings" soldr cargo doc --workspace --no-deps exit 0
• Boundary suites: ci.test_platform_boundary_research + ci.test_enforce_platform_boundary + ci.test_rust_toolchain_pins (35 tests) OK; research check green on all three host labels
• LOC gate clean (largest touched file is pre-baselined lpc.rs, now smaller)

Refs #1314

Co-Authored-By: Claude noreply@anthropic.com

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: edf62fbd-a110-41eb-83ab-9262a8dde967

📥 Commits

Reviewing files that changed from the base of the PR and between b02262d and ce709df.

⛔ Files ignored due to path filters (2)

• ci/platform_boundary_ledger.tsv is excluded by !**/*.tsv
• ci/platform_boundary_research.tsv is excluded by !**/*.tsv

📒 Files selected for processing (21)

• ci/test_enforce_platform_boundary.py
• crates/fbuild-core/src/platform/device.rs
• crates/fbuild-core/src/platform/host.rs
• crates/fbuild-core/src/platform/linux/device.rs
• crates/fbuild-core/src/platform/linux/host.rs
• crates/fbuild-core/src/platform/linux/mod.rs
• crates/fbuild-core/src/platform/macos/device.rs
• crates/fbuild-core/src/platform/macos/host.rs
• crates/fbuild-core/src/platform/macos/mod.rs
• crates/fbuild-core/src/platform/windows/device.rs
• crates/fbuild-core/src/platform/windows/host.rs
• crates/fbuild-core/src/platform/windows/mod.rs
• crates/fbuild-deploy/src/lpc.rs
• crates/fbuild-deploy/src/lpc_debugger_reflash.rs
• crates/fbuild-deploy/src/probe_rs.rs
• crates/fbuild-deploy/src/rp2040.rs
• crates/fbuild-deploy/src/rp2040_mount.rs
• crates/fbuild-deploy/src/rp2040_topology.rs
• crates/fbuild-serial/src/ports.rs
• crates/fbuild-serial/src/sysfs_usb.rs
• dylints/enforce_platform_boundary/src/baseline.txt

💤 Files with no reviewable changes (1)

• dylints/enforce_platform_boundary/src/baseline.txt

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change moves host and device platform behavior into fbuild-core. Deployment code uses shared home-directory and mounting facades. RP2040 topology consumes platform serial facts. Serial health enrichment runs through a cross-platform no-op boundary. Platform-boundary expectations are reduced.

Changes

Platform behavior migration

Layer / File(s)	Summary
Core platform facades and backends crates/fbuild-core/src/platform/..., ci/test_enforce_platform_boundary.py, dylints/enforce_platform_boundary/src/baseline.txt	Added shared home-directory and block-device mounting APIs. Added Windows serial location information. Added Linux, macOS, and Windows backend implementations. Updated boundary expectations.
Deployment platform integration crates/fbuild-deploy/src/lpc.rs, crates/fbuild-deploy/src/lpc_debugger_reflash.rs, crates/fbuild-deploy/src/probe_rs.rs, crates/fbuild-deploy/src/rp2040.rs, crates/fbuild-deploy/src/rp2040_mount.rs	Deployment paths use the shared home-directory resolver. RP2040 mounting uses the platform device facade and a platform-neutral helper name.
Topology and serial-port data flow crates/fbuild-deploy/src/rp2040_topology.rs, crates/fbuild-serial/src/ports.rs, crates/fbuild-serial/src/sysfs_usb.rs	Topology lookup uses enumerated serial facts on all hosts. Serial health enrichment runs unconditionally and remains unchanged when sysfs is unavailable. Tests and diagnostic links were updated.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to ce709

This change centralizes platform-specific device and host behavior behind the facade while preserving the reported verification results; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Deployment
  participant fbuild_core
  participant PlatformBackend
  participant SerialEnumeration
  Deployment->>fbuild_core: request home directory or mount device paths
  fbuild_core->>PlatformBackend: delegate selected platform operation
  PlatformBackend-->>fbuild_core: optional home path or mount processing
  fbuild_core-->>Deployment: return platform result
  SerialEnumeration->>fbuild_core: enumerate serial-port facts
  fbuild_core-->>SerialEnumeration: return location and identity data

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 58.54% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 41 functions across 20 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: moving device-specific consumer logic behind a neutral platform facade.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/platform-phase-8-device-consumers

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}