Repository navigation
Description
M6.5.5–6 — kontrolowany refactor KISS / DRY / clean-code
Bazowy stan audytu: main = 36ab3c70a47d7651baa7f27dbfedd4543eb5ef9f po zakończeniu M6.5.4.
Cel
Zmniejszyć złożoność implementacyjną i duplikację przed bramką sprzętową H1, bez zmiany funkcjonalności produktu, kontraktów bezpieczeństwa, zachowania protokołu, goldens ani semantics evidence.
Refactor jest wykonywany małymi krokami, jeden obszar / plik / odpowiedzialność na PR. Nie wykonujemy jednego szerokiego rewrite.
Niezmienniki — DO NOT CHANGE
Każdy punkt poniżej jest release-blocking. Refactor nie może:
- tworzyć drugiego
BusActor, drugiegoWriteCoordinatorani drugiego authority sesji; - przenieść decyzji authorization/audit/operation poza
SessionStateMachine; - umożliwić write bez Verified + trust + Armed + healthy audit + prepare/confirm + durable prepare;
- zmienić zasady: dokładnie jeden physical write, zero retry write, zero rollback, zero auto-resume;
- osłabić exact operator confirmation lub normalizować whitespace confirmation;
- usuwać powtórnych safety re-checków wykonywanych bezpośrednio przed physical write;
- rozszerzyć restore poza allowlistę
NormaliApprovedRestorePlan+RestoreOperationPermit; - zmienić scheduler/budget semantics, kolejność klas, RTU budget ani QueueFull behavior bez osobnego feature issue;
- zmienić committed conformance evidence [PLAN 01] Zablokować architekturę modularnego monolitu Rust #1–Create logical issue #6 commit #40 ani ich znaczenia;
- zmienić packaged/local profile trust semantics;
- przenieść filesystem I/O poza storage/composition boundaries;
- wprowadzić nowe timers/queues/transport owners tylko w celu refaktoru.
Obowiązkowy odbiór każdego PR
Każdy PR z tej listy musi mieć:
cargo fmt --check;- Clippy
-D warnings; - architecture gate;
- wszystkie istniejące unit/integration/nextest;
- process-level PTY acceptance;
- committed conformance [PLAN 01] Zablokować architekturę modularnego monolitu Rust #1–Create logical issue #6 commit #40 bez osłabienia;
- supply-chain gate;
- brak nowych funkcjonalności ukrytych w refaktorze;
- diff ograniczony do jednego logicznego kroku;
- po merge — post-merge CI na
main.
Backlog wykonawczy
R1 — TUI state DRY cleanup — P0 / najniższe ryzyko
R1a — deduplikacja zmiany ekranów w ui_state.rs
- Wydzielić jeden helper zmiany ekranu/resetu transient navigation state.
-
SelectScreen,NextScreen,PreviousScreenkorzystają z tej samej ścieżki. -
OpenParameterIndexzachowuje własny wskazany index, ale współdzieli bezpieczny reset edycji/form. - Bez zmiany key bindings, focus semantics, scroll semantics i editor behavior.
R1b — deduplikacja lifecycle wyszukiwania w ui_state.rs
- Wydzielić wspólne begin/apply/clear dla Profile/Scope/Parameter search, o ile borrow/API pozostają prostsze niż obecny kod.
- Zachować
.trim()wyłącznie dla search/filter text. - Nie dotykać exact write/restore confirmation text.
R1c — poprawa nazewnictwa edit mode
- Zmienić mylącą nazwę
ConnectionEditna neutralną (ActiveEdit/EditMode) we wszystkich TUI call sites. - Zero zmian zachowania.
R2 — application.rs physical split — P0
Obecny hotspot: około 82 KB i wiele use-case’ów w jednym module.
- Zachować dokładnie jeden
ApplicationStatei jeden reducer authority. - Rozdzielić implementację fizycznie, np.
application/state.rs,view.rs,connection.rs,monitoring.rs,parameters.rs,faults.rs,backup_restore.rs,session.rs. - Najpierw move-only / visibility-only; bez zmiany logiki.
- Publiczny
ApplicationAction,ApplicationEffect,ApplicationViewzachowują semantykę. - Nie wykonywać jednocześnie narrowing public API.
R3 — poll.rs physical split — P0
Obecny hotspot: około 71 KB; model + planner + cost/budget + executor w jednym pliku.
- Rozdzielić na
poll/model.rs,planner.rs,cost.rs,executor.rs(nazwy mogą zostać dopasowane do kodu). -
PollPlanpozostaje pojedynczym SPoT. - Zero zmian degradation order, budget rank, cadence, grouping, deadline/catch-up semantics.
- Conformance Validate implementation of issue #6 #36–Create logical issue #6 commit #40 musi pozostać bit-for-bit semantycznie równoważne.
R4 — write_coordinator.rs internal split — P0 / wysokie ryzyko
Obecny hotspot: około 100 KB — największy moduł aplikacji.
- Zachować
WriteCoordinatorjako jedyny physical write authority. - Rozdzielić manual-write, restore, shared execution/readback/audit helpers wewnętrznie.
- Nie eksportować możliwości mintowania
PreparedBusWrite. - Nie zmieniać kolejności trust/drive-state/old-value/audit/physical-write/readback checks.
- Nie usuwać safety re-checków tylko dlatego, że wyglądają na duplikację.
- Dopiero po move-only split rozważyć scalenie duplikacji
abort_restore/abort_restore_in_place. - Write/restore conformance [PLAN 14] Zbudować dashboard i wielokanałowy scope #14–Validate implementation of issue #5 #35 musi pozostać nieosłabione.
R5 — monitoring_runtime.rs split — P0/P1
Obecny hotspot: około 48 KB; orchestration + planner/executor + pipeline + CSV + snapshots.
- Rozdzielić composition glue od subscription planning, CSV bridge i snapshot/consumer glue.
- Nie tworzyć dodatkowych timers, queues ani runtime owners.
- Poll/telemetry SPoT pozostają w application layer.
- Slow sink nadal nie może wpływać na RTU latency (Create logical issue #6 commit #40).
R6 — TUI keymap split — P1
- Rozbić duży
keymap.rs(~31 KB) według ekranów/odpowiedzialności. - Zachować istniejące
parameter_keymap.rsifault_keymap.rsjako feature boundaries. - Centralizować help/key-binding labels tam, gdzie eliminuje to drift bez komplikowania modelu.
- Żaden renderer nie dostaje adaptera/transportu.
R7 — screens.rs renderer split — P1
- Przenieść proste renderery ekranów do małych modułów.
- Nie duplikować już istniejących dedicated renderers: monitoring/fault/parameter/backup/bus diagnostics.
- Pure presentation only.
R8 — zawężenie publicznego API lantern-app — P1
- Dopiero po R2–R4 ograniczyć nadmierne
pub use ...::*. - Zachować publiczne typy wymagane przez composition/tests.
- Każde usunięcie exportu musi być potwierdzone pełnym workspace buildem, docs i examples.
R9 — storage mechanical splits — P1 / ostrożnie
Kolejno, nie równolegle:
-
audit.rs(~42 KB), -
csv_writer.rs(~40 KB), -
backup.rs(~26 KB), -
diagnostics_bundle.rs(~25 KB).
Zasady: move-only najpierw; atomic/fsync/permissions/path-traversal semantics bez zmian.
R10 — transport internal cleanup — P2 / po głównym dry cleanup
-
bus_actor.rssplit tylko jeśli realnie poprawia czytelność. - Nigdy nie tworzyć drugiego aktora/queue authority.
- Scheduler fairness, safety burst, T3.5, retry policy i metrics pozostają bez zmian.
-
unsafenadal wyłącznie w izolowanymrs485_ioctl.rs.
R11 — process/conformance test helper DRY — P2
- Wyciągnąć wspólne PTY spawn/terminal-screen reconstruction/helpers z process acceptance.
- Nie zmieniać oczekiwań testów ani golden evidence.
- Ten punkt realizować dopiero po refaktorach production code, aby nie zmieniać jednocześnie kodu i jego głównego harnessu.
R12 — clean-code/docs status — P2
- README: usunąć nieaktualny
architecture bootstrap / pre-alphai opisać rzeczywisty etap przed H1. - Usunąć stare placeholder/status texty, jeśli jeszcze istnieją.
- Uporządkować nazwy modułów po refaktorach.
- Zaktualizować diagram/module map docs bez deklarowania hardware qualification przed H1.
R13 — final dry-code audit / bramka M6.5
- Full CI Debian 13 amd64.
- Architecture gate green.
- Wszystkie process PTY E2E green.
- Conformance committed [PLAN 01] Zablokować architekturę modularnego monolitu Rust #1–Create logical issue #6 commit #40 green i semantycznie nieosłabione.
- Porównanie feature surface przed/po: connection, dashboard, scope, faults, parameters, guarded write, backup/diff/restore, diagnostics, CSV, reconnect.
- Brak nowego authority/state/timer/queue tylko z powodu refaktoru.
- Dopiero po tym roadmapa przechodzi do H1 sprzęt.
Kolejność zatwierdzona po analizie ryzyka
R1a → R1b → R1c → R2 → R3 → R4 → R5 → R6 → R7 → R8 → R9 → R10 → R11 → R12 → R13
Uzasadnienie:
- zaczynamy od lokalnego, łatwo odwracalnego DRY w TUI;
- następnie wykonujemy move-only splity application i poll;
- safety-critical
WriteCoordinatordopiero po ustabilizowaniu prostszych granic; - public API narrowing dopiero po splitach, żeby nie mieszać dwóch rodzajów zmian;
- storage/transport późno ze względu na wysoki koszt regresji;
- test harness DRY dopiero po production code, żeby nie zmieniać równocześnie systemu i jego głównego dowodu;
- docs/final audit zamykają M6.5.
Definition of Done tego issue
Issue można zamknąć wyłącznie po R13. Żaden checkbox nie oznacza DONE bez green CI na exact head i green post-merge CI. Sprzęt/HIL nie jest częścią tego issue; zaczyna się dopiero po jego zamknięciu zgodnie z #26/#25.
Activity
KeyffMS commentedon Sep 14, 2026
Review backlogu po utworzeniu
Lista została ponownie przeanalizowana pod kątem ryzyka regresji i kolejność pozostaje zatwierdzona.
Najważniejsze decyzje wykonawcze:
WriteCoordinator, bo są łatwiejsze do odbioru i zmniejszają churn przed safety-critical split;BusActornie daje jednoznacznego uproszczenia bez zwiększenia coupling, zostaje świadomie pominięty i udokumentowany jakonot needed;Pierwszy wykonywany krok: R1a —
ui_state.rs, deduplikacja przełączania ekranów/resetu transient state. To jest lokalny refactor bez zmiany keymap, application actions, write/restore confirmation ani runtime behavior.refactor: deduplicate TUI screen transitions (R1a)
KeyffMS commentedon Sep 14, 2026
R1a — DONE
26b6d1d27b747929fd65d0dfa1301b0d0e3e9c0a.mainCI #1037: green.crates/lantern-tui/src/ui_state.rs.OpenParameterIndexwspółdzieli reset i zachowuje jawnie żądany index.Następny wykonywany punkt: R1b — wspólny lifecycle Profile/Scope/Parameter search.
refactor: deduplicate TUI search lifecycle (R1b)
KeyffMS commentedon Sep 14, 2026
R1b — DONE
263eb058f654b9ddc7da6b90d7e686fdd78f1a7c.main:b2e59b7e10c3bc1ce10d5c4e42ed3d56e4f49a90.mainCI #1039: green on the merge commit.crates/lantern-tui/src/ui_state.rs..trim()remains limited to search/filter apply.Next checkpoint: R1c — rename
ConnectionEditto a neutralActiveEdit/EditMode, zero behavioral change.refactor: rename TUI edit mode to ActiveEdit (R1c)
KeyffMS commentedon Sep 14, 2026
R1c — DONE
82b69b3d20229b661fd6075fe0eece163f673d1f.1bc36f34f658e64037e8d378edf6714ed9c05ac1.mainCI #1041: green on exact merge commit.ConnectionEdit/connection_editrenamed to neutralActiveEdit/active_edit.Następny wykonywany punkt: R2 — physical split
application.rs, zachować jedenApplicationStatei jeden reducer authority. R2 będzie wykonywany małymi move-only PR-ami. Pierwszy podkrok: wydzieleniereduce_faultsdoapplication/faults.rs; backup/restore nie jest pierwszym podkrokiem, ponieważ obecny architecture gate wiąże exact-confirmation guard bezpośrednio zapplication.rsi nie może zostać po cichu osłabiony.refactor: split application fault reducer (R2a)
KeyffMS commentedon Sep 15, 2026
R2a — DONE
cb8b99717f32c40c5d2909ca3dcb50c6e14e7dcc.main:cac3479f2efd083bb9043383c31320accb5c99fb.mainCI #1046: green on the exact merge commit.crates/lantern-app/src/application.rs+ new privatecrates/lantern-app/src/application/faults.rs.ApplicationState::reduce_faultsmoved physically without logic changes; singleApplicationStateand single top-level reducer authority remain inapplication.rs.-D warnings; the import was removed withoutallow/gate weakening and the full immutable gate was rerun from scratch.Next R2 substep: R2b — move-only
reduce_monitoringto privateapplication/monitoring.rs, keeping monitoring state ownership and the top-level dispatcher unchanged.KeyffMS commentedon Sep 15, 2026
R2a — DONE
cb8b99717f32c40c5d2909ca3dcb50c6e14e7dcc.main:cac3479f2efd083bb9043383c31320accb5c99fb.mainCI #1046: green on exact merge commit.crates/lantern-app/src/application.rsand newcrates/lantern-app/src/application/faults.rs.ApplicationStateand the top-levelreduce()dispatcher remain single authorities inapplication.rs.reduce_faultsmoved verbatim to a private child module; only method visibility changed topub(super).-D warnings; it was fixed mechanically with no gate weakening.Next checkpoint: R2b — move-only split
reduce_monitoringtoapplication/monitoring.rs.refactor: split application monitoring reducer (R2b)
KeyffMS commentedon Sep 15, 2026
R2b — DONE
bd82b4af67c1470bd2944800b706fbd66f326390.main:e5b3de90b95446a443bbb12dac17ceaff408baae.mainCI #1048: green on exact merge commit.crates/lantern-app/src/application.rsand newcrates/lantern-app/src/application/monitoring.rs.ApplicationStateand the top-levelreduce()dispatcher remain the single authorities inapplication.rs.reduce_monitoringmoved verbatim; only method visibility changed topub(super).Next checkpoint: R2c — move-only connection reducer/helper split.
KeyffMS commentedon Sep 16, 2026
R2c — DONE
refactor: split application connection reducer (R2c)120ef99997614976500e341a5a2b3d375b56a6af40ba24ffe16b34da5942fd32d9bb43be6ca27510crates/lantern-app/src/application/connection.rs; exactly oneApplicationStateand the top-level reducer authority remain inapplication.rs; write/restore confirmation paths and their architecture-gate evidence were not moved or weakened.R2 remains in progress. Proceeding directly to the next smallest low-risk move-only split.
KeyffMS commentedon Sep 16, 2026
R2d — DONE
Wydzielono move-only / visibility-only projekcję aplikacji do
crates/lantern-app/src/application/view.rs:SessionPhaseView,AuthorizationView,AuditHealthView,OperationView;SessionViewi jego projekcję;ApplicationViewi jego projekcję;port_label.Zachowano dokładnie jeden
ApplicationStatei głównyApplicationState::reducewapplication.rs. Write/restore exact operator confirmation pozostały bez zmian wapplication.rs, więc istniejący architecture gate nadal obejmuje tę ścieżkę bez osłabienia.PR: #91
Pierwszy exact-head CI #1051 na
1aab22a6342bda214f1e8928211762df98a0e3f8wykrył wyłącznie stale rustfmt. Poprawiono tylko formatowanie importów, bez zmiany semantyki i bez osłabiania gate'ów.Final exact PR head:
554505d74210651e58a5adedd73ca484b9fe05dbExact-head CI #1052: success
Merge:
68afc9508b6efc846e2d3aafabfee9e89296f10dPost-merge CI #1053 na dokładnym merge SHA: success
R2 jako całość pozostaje w toku.
KeyffMS commentedon Sep 16, 2026
R2e — DONE
Wydzielono move-only / visibility-only prywatne substany aplikacji do
crates/lantern-app/src/application/state.rs:ApplicationMonitoringState;ApplicationParameterState;Default/for_profile.Zastosowano wyłącznie
pub(super)wymagane przez parent/sibling application modules.ApplicationStatei głównyApplicationState::reducepozostały wapplication.rs. Write/restore exact operator confirmation pozostały bez zmian wapplication.rs, więc architecture gate nadal obejmuje te ścieżki bez osłabienia.PR: #92
Pierwszy exact-head CI #1054 na
4572f575a0f399bf310784799b57c82b535dbffewykrył wyłącznie stale rustfmt. Poprawiono tylko formatowanie, bez zmiany semantyki i bez osłabiania gate'ów.Final exact PR head:
54db50e6922bbe07788ce67b9289ccfb996ac33dExact-head CI #1055: success
Merge:
2dfb7300d08fbb85e4715de26c6ae60f57e7ce0fPost-merge CI #1056 na dokładnym merge SHA: success
R2 jako całość pozostaje w toku.
KeyffMS commentedon Sep 16, 2026
R2f — DONE
ApplicationState::viewimplementation intocrates/lantern-app/src/application/view.rsb263823b840980c59c9c460c9c4af5fc144ff0160d5d004f92a3d764a84d4794b381bd2c75141013ApplicationStateand the top-levelApplicationState::reduceremain inapplication.rsapplication.rs; architecture-gate coverage was not weakenedNext: R2g — continue the smallest low-risk move-only physical split of
application.rs.KeyffMS commentedon Sep 16, 2026
R2g — DONE
session_fault_for_connect_errorfromcrates/lantern-app/src/application.rsintocrates/lantern-app/src/application/connection.rs1b83c2004ab260a796b71ae4d96263b2c5c18b8e8bcbc4942387505a34bd783470479ce23338a615ApplicationStateand the top-levelApplicationState::reduceremain inapplication.rsapplication.rs; architecture-gate coverage was not weakenedNext: R2h — continue the smallest low-risk move-only physical split of
application.rs.KeyffMS commentedon Sep 19, 2026
R2h — DONE
ApplicationEffectError,EffectRunner, andApplicationRuntimeintocrates/lantern-app/src/application/runtime.rs.application.rs;ApplicationAction,ApplicationEffect, exactly oneApplicationState, and the top-levelApplicationState::reduceremain in the root module.application.rs; no architecture/conformance gate was weakened.75c9b9fe3d70b57d2e98f59be83c965b7a164063.successon that exact SHA.511817d429aa76c9ff1b6441668da895ee7aa6bf.successon exact merge SHA511817d429aa76c9ff1b6441668da895ee7aa6bf.R2h is DONE only after the green post-merge gate above.
KeyffMS commentedon Sep 19, 2026
R2i — DONE
ApplicationStateconstruction/accessor implementation (Default,with_registry,with_registry_and_suggestions,registry,session) into the existingcrates/lantern-app/src/application/state.rs.ApplicationStatedefinition and the top-levelApplicationState::reduceremain inapplication.rs.application.rs; no architecture/conformance gate was weakened.919eeb35829140acce8966da77977bdca42270ec.successon that exact SHA.dc9624dbaf2cd5f8a6ada0b14c30f2abfcc30fc8.successon exact merge SHAdc9624dbaf2cd5f8a6ada0b14c30f2abfcc30fc8.R2i is DONE only after the green post-merge gate above.
KeyffMS commentedon Sep 20, 2026
R2j — DONE
ApplicationState::selected_profileandApplicationState::profile_candidateshelpers intocrates/lantern-app/src/application/state.rs, with sibling-onlypub(super)visibility.ApplicationStatedefinition and the top-levelApplicationState::reduceremain inapplication.rs.application.rs; no architecture/conformance gate was weakened.ed091d43984c4e555246bca59891d457a3e6fbe4.successon that exact SHA.3c2b121a9b378b5d8e879378ec6e62014a70b780.successon exact merge SHA3c2b121a9b378b5d8e879378ec6e62014a70b780.R2j is DONE only after the green post-merge gate above.