[PLAN 22] Zbudować obserwowalność, trwały AuditPort i pakiet diagnostyczny

[KeyffMS]

Cel

Zapewnić lokalną obserwowalność, produkcyjną implementację trwałego AuditPort wymaganego przez #16 oraz bezpieczny pakiet diagnostyczny — bez telemetrii sieciowej i bez blokowania read-only RTU.

Granica architektoniczna

• Implementacje plikowe należą do lantern-storage.
• Porty są definiowane w lantern-app.
• [PLAN 22] Zbudować obserwowalność, trwały AuditPort i pakiet diagnostyczny #22 nie zależy od restore i dostarcza audit primitives wcześniej.
• Po [PLAN 22] Zbudować obserwowalność, trwały AuditPort i pakiet diagnostyczny #22 write nadal nie jest user-reachable bez [PLAN 23] Zamknąć profile trust, bezpieczeństwo funkcjonalne i supply chain #23.

Logi diagnostyczne

• tracing stack z [PLAN 02] Ustalić toolchain, wersje zależności i politykę aktualizacji #2;
• strukturalne pola session/request/profile/fingerprint/component/operation/outcome/time;
• JSONL w XDG state, 0600, non-blocking;
• bounded ring 2000 zdarzeń dla TUI;
• dropy liczone;
• VFD_LANTERN_LOG nie wyłącza audytu;
• brak pełnych ramek, strumienia telemetrycznego i old/new write values w zwykłym logu;
• retencja 7 plików diagnostycznych, bez audytów;
• brak endpointu sieciowego.

AuditPort API

record_decision

record_decision(DecisionAuditRecord)

Dla decyzji powstałych przed fizycznym write:

• Expired;
• Cancelled;
• RejectedByPolicy;
• ProfileNotTrusted;
• PreconditionChanged.

Nie przyjmuje i nie tworzy PreparedToken.

Jeżeli record_decision zwróci błąd:

• nie istnieje trwały rekord tej decyzji;
• aplikacja zwraca runtime outcome AuditUnavailable, rozbraja i ustawia audit health Degraded;
• zwykły logger może zapisać wyłącznie best-effort diagnostykę;
• AuditPort nie próbuje rekurencyjnie zapisać własnej awarii i nie deklaruje rekordu, którego nie utrwalił.

prepare_device_write

prepare_device_write(DeviceWritePreparation) -> PreparedToken

• rekord Prepared zawiera plan/context hash, session, fingerprint, profile hash, parameter, old/target raw/engineering, funkcję i request ID;
• journal append + trwała synchronizacja;
• atomowy update head + synchronizacja katalogu;
• dopiero potem zwracany jest single-use token;
• błąd = zero write, disarm i audit_health = Degraded.

finalize_device_write

finalize_device_write(PreparedToken, DeviceWriteOutcome, ReadBackEvidence)

Akceptuje wyłącznie outcomes po rozpoczęciu write:

• Verified;
• DeviceRejected;
• ReadBackMismatch;
• OutcomeUnknown;
• TransportLost;
• AuditDegraded.

Token jest konsumowany, związany z PlanId/RequestId i nie może finalizować innej operacji.

Operacje wielokrokowe

begin_operation(OperationAuditStart) -> OperationToken
finish_operation(OperationToken, OperationAuditFinish)

• begin_operation trwale zapisuje i synchronizuje operation start oraz head przed zwróceniem tokenu.
• OperationToken jest single-use, non-clone i związany z operation ID, backup ID, plan hash, SessionId, fingerprint i profile hash.
• Restore permit z [PLAN 17] Zbudować bezpieczny backup, semantyczny diff i ograniczony restore #17 może powstać dopiero po poprawnym begin_operation i zawiera ten token jako prywatną capability.
• Błąd begin_operation oznacza brak permitu, zero write, disarm i audit health Degraded.
• finish_operation konsumuje token i zapisuje finish/abort wraz z końcowym indeksem oraz podsumowaniem kroków.
• Błąd finish_operation po wykonaniu któregokolwiek kroku ustawia Degraded; nie jest przedstawiany jako niewykonanie wcześniejszych zapisów.
• API zna operation ID, backup ID, plan hash i step index, ale nie zależy od implementacji restore.

Journal i head

• audit_<SessionId>.jsonl;
• audit_<SessionId>.head.json;
• head: schema, session, record count, head hash, last time, open/finalized;
• rekordy JCS, previous_hash i record_hash;
• float jako bits/text, bez NaN JSON number;
• append/sync, potem atomowy head/sync directory.

Rzeczywista gwarancja

Mechanizm wykrywa przypadkowe uszkodzenie, zmianę/brak rekordu, ucięty ogon i rollback względem niezmienionego head. Crash window klasyfikuje jako Interrupted. Nie jest kryptograficznym dowodem przeciw właścicielowi konta mogącemu przepisać cały journal/head.

Audit health

• Każdy błąd record_decision, prepare_device_write albo begin_operation degraduje audit health i blokuje write w tej logicznej sesji.
• Błąd finalize_device_write albo finish_operation po wykonanym write natychmiast ustawia Degraded.
• audit_health = Degraded jest częścią [PLAN 09] Zbudować maszynę stanu sesji, identyfikację i reconnect #9 i przeżywa reconnect.
• Może zniknąć tylko po nowym SessionId.

Weryfikator offline

ValidFinalized, ValidOpen, Interrupted, RecordChanged, RecordMissing, TailTruncated, HeadMissing, HeadMismatch, RollbackDetected, UnsupportedSchema.

Nie naprawia automatycznie.

Diagnostyka

DiagnosticsSnapshot składa session state, BusStats, PollPlan, pipeline/storage queues i CSV drops.

Pakiet diagnostyczny do XDG data/jawnej ścieżki zawiera domyślnie zredagowane build/system/config/ports/profile hashes/identification report/stats/logs/manifest. Values, CSV, backup, fault report, pełny profil i audit wymagają osobnego opt-in.

Panic i shutdown

• Panic hook instaluje composition root zgodnie z [PLAN 12] Zbudować szkielet TUI w Ratatui z jednokierunkowym przepływem stanu #12.
• Najpierw restore terminala, potem minimalny panic report.
• Finalizacja audytu ma pierwszeństwo przed zwykłym loggerem.

Testy

• tracing i redakcja;
• log queue pressure;
• record_decision bez tokenu;
• awaria record_decision nie tworzy fikcyjnego rekordu ani rekurencyjnego audytu;
• niemożliwość finalize pre-write decision przez PreparedToken;
• prepare append/fsync/head failures = zero write + Degraded;
• PreparedToken single-use/context binding;
• begin_operation failure = zero permit/zero write + Degraded;
• OperationToken single-use/context binding;
• finish_operation failure po krokach = sticky Degraded;
• finalize failure = sticky Degraded;
• hash chain/crash windows;
• Degraded przez reconnect;
• retencja bez audytów;
• diagnostyka opt-in;
• panic terminal restore.

Kryteria akceptacji

• AuditPort ma jedną implementację produkcyjną w storage.
• Decyzje pre-write, device prepare/finalize i operation begin/finish mają oddzielne, typowane API.
• Wynik pre-write nie wymaga fikcyjnego PreparedToken.
• AuditUnavailable nie jest rekurencyjnie audytowany ani przedstawiany jako trwały rekord.
• Write nie jest wysyłany bez trwałego Prepared/head.
• Restore permit nie istnieje bez trwałego operation start.
• Błąd dowolnej krytycznej operacji audytu ustawia sticky Degraded zgodnie z etapem wykonania.
• Weryfikator poprawnie klasyfikuje uszkodzenie i przerwanie.
• Dokumentacja nie zawyża gwarancji hash-chain.
• Journal/head nie podlegają retencji.
• Monitoring read-only nie jest blokowany.
• Brak połączeń sieciowych.

Zależności

• [PLAN 01] Zablokować architekturę modularnego monolitu Rust #1
• [PLAN 06] Ustalić konfigurację aplikacji, CLI i katalogi XDG #6
• [PLAN 08] Zaimplementować pojedynczy aktor magistrali Modbus RTU #8
• [PLAN 09] Zbudować maszynę stanu sesji, identyfikację i reconnect #9
• [PLAN 12] Zbudować szkielet TUI w Ratatui z jednokierunkowym przepływem stanu #12
• [PLAN 16] Zbudować dwuetapowy core prepare/confirm zapisu #16