[PLAN 02] Ustalić toolchain, wersje zależności i politykę aktualizacji

[KeyffMS]

Cel

Ustanowić jeden reprodukowalny baseline technologiczny dla Debiana 13 Trixie, usunąć niespójność obecnego manifestu i centralnie zablokować biblioteki, feature’y oraz narzędzia projektu.

Decyzje bezalternatywne

• Docelowy system uruchomieniowy: Debian 13 Trixie, architektury amd64 i arm64.
• rustup jest instalowany z pakietu APT Trixie. Projekt nie używa curl | sh ani systemowego rustc do buildów produkcyjnych.
• rust-toolchain.toml: Rust 1.97.1 z rustfmt, clippy i llvm-tools-preview tam, gdzie wymaga tego coverage.
• Workspace: edition = "2024", rust-version = "1.97".
• Obecne rust-version = "1.85" zostaje usunięte.
• Cargo.lock jest obowiązkowo wersjonowany; buildy, testy, narzędzia i wydania używają --locked.
• Produkt, symulator, generatory i testy pozostają bez Pythona.

Polityka wersji

• Wszystkie bezpośrednie zależności produkcyjne i deweloperskie są zadeklarowane centralnie w [workspace.dependencies].
• Bezpośrednie zależności używają dokładnych wymagań =x.y.z; Cargo.lock blokuje cały graf przechodni.
• Wszystkie binarne narzędzia Cargo i dokumentacji są zapisane z dokładną wersją w jednym repozytoryjnym tools.lock.toml.
• Pierwszy PR realizujący [PLAN 02] Ustalić toolchain, wersje zależności i politykę aktualizacji #2 rozwiązuje dla każdego wskazanego narzędzia najnowszą nieyankowaną wersję, która kompiluje się na Rust 1.97.1, zapisuje dokładny numer i od tej chwili baseline jest zamrożony.
• Zmiana dowolnej wersji następuje tylko osobnym PR-em wraz z pełnym CI i aktualizacją lockfile/tool manifestu.

Zablokowane biblioteki produkcyjne

• anyhow 1.0.104 — wyłącznie binarium i granice CLI;
• thiserror 2.0.19 — błędy bibliotek;
• clap 4.6.4 — CLI;
• ratatui 0.30.2 — TUI;
• crossterm 0.29.0 — terminal;
• tokio 1.53.1 — runtime;
• tokio-util 0.7 — CancellationToken;
• futures-util 0.3 — strumienie;
• tokio-modbus 0.17.0, bez default features, z rtu; w symulatorze także rtu-server;
• tokio-serial 5.5.0 — port szeregowy;
• udev 0.9.3 — discovery i hotplug;
• nix 0.31.3 i libc 0.2 — PTY, wyłączność i Linux RS-485 ioctl;
• serde 1.0.229, serde_json 1.0.151, toml 1.1.3 — serializacja;
• serde_jcs 0.2.0 — RFC 8785 JCS;
• schemars 1.2.2 — JSON Schema;
• serde_path_to_error 0.1.20 — ścieżki błędów;
• rust_decimal 1.42.1 — wartości stałoprzecinkowe;
• csv 1.4.0 — CSV;
• time 0.3.54 — czas UTC i formaty;
• directories 6.0.0 — katalogi XDG;
• sha2 0.11.0 — SHA-256;
• tracing 0.1.44, tracing-subscriber 0.3.23, tracing-appender 0.2.5 — obserwowalność;
• tempfile 3.27.0 — pliki tymczasowe i zapisy atomowe.

Dokładne wymagania =x.y.z dla pozycji zapisanych powyżej jako linia kompatybilności 0.x zostają utrwalone w pierwszym PR #2 zgodnie z deterministyczną regułą wersji i nie są wybierane ponownie przez późniejsze issues.

Feature policy

• ratatui:

ratatui = { version = "=0.30.2", default-features = false,
  features = ["all-widgets", "crossterm_0_29", "layout-cache", "macros", "underline-color"] }

• crossterm:

crossterm = { version = "=0.29.0", features = ["event-stream"] }

• Tokio nie używa full; dozwolone są wyłącznie macros, rt-multi-thread, signal, sync, time, fs, io-util oraz feature wymagany przez konkretny adapter.
• Wyłączać default features, gdy wnoszą nieużywane backendy lub formaty.
• Jedna biblioteka na jedną odpowiedzialność. Nie dodawać równoległych bibliotek konfiguracji, czasu, logowania, terminala, Modbus, CSV ani kanonikalizacji JSON.

Biblioteki testowe i deweloperskie

Wybrane narzędzia są bezalternatywne; ich dokładne wersje trafiają do tools.lock.toml/workspace w #2:

• proptest — property tests;
• insta — świadomie zatwierdzane snapshoty;
• criterion — mikrobenchmarki;
• rand_chacha — jedyny deterministyczny RNG symulatora;
• clap_mangen i clap_complete — man page i completions z jednego modelu CLI.

Narzędzia Cargo i dokumentacji

• cargo-nextest;
• cargo-hack;
• cargo-machete;
• cargo-deny;
• cargo-audit;
• cargo-vet;
• cargo-cyclonedx;
• cargo-about;
• cargo-auditable;
• cargo-llvm-cov;
• cargo-mutants;
• cargo-fuzz;
• cargo-dist;
• cargo-deb;
• mdbook.

Weryfikacja supply chain używa polecenia cargo vet check. Nie używać nieistniejącego cargo vet verify.

Zależności systemowe Trixie

Build i CI:

• build-essential;
• ca-certificates;
• git;
• libudev-dev;
• pkg-config;
• rustup.

Runtime pakietu jest wyliczany przez dpkg-shlibdeps. socat może być pomocniczym narzędziem ręcznym, ale produkt i podstawowe testy go nie wymagają.

Polityka aktualizacji

• Dependabot otwiera cotygodniowe PR-y dla Cargo i GitHub Actions.
• Aktualizacja patch/minor wymaga pełnego CI, profili, symulatora i scenariuszy zgodności.
• Aktualizacja major, zmiana podstawowej biblioteki, feature setu lub MSRV wymaga ADR-u.
• Actions są przypięte do pełnych SHA, obrazy do digestów.
• Zakazane są wildcard versions, niezatwierdzone git dependencies, aktywne advisories, nieakceptowalne licencje i nowy unsafe poza zatwierdzonym modułem ioctl.

Kryteria akceptacji

• Czysty debian:trixie-slim po instalacji pakietów APT buduje projekt bez Pythona, bez curl | sh i bez systemowego rustc.
• cargo build --workspace --locked, testy, Clippy i dokumentacja działają na Rust 1.97.1.
• Wszystkie bezpośrednie zależności mają dokładne wersje w jednym miejscu.
• Każde narzędzie ma dokładną wersję w tools.lock.toml oraz udokumentowane polecenie instalacji z --locked.
• Ratatui używa jawnie backendu crossterm_0_29, a Crossterm feature event-stream.
• Manifest nie deklaruje MSRV niższego od wymagań zależności.
• cargo machete, cargo deny check, cargo audit i cargo vet check są zielone.
• Nie ma dwóch bibliotek pełniących tę samą odpowiedzialność.

Zależności

• [PLAN 01] Zablokować architekturę modularnego monolitu Rust #1