> > > Mvp

SOTER MVP — Lokalny Podręcznik CLI i Architektury (Local-First MVP)

Podręcznik ten opisuje architekturę i obsługę wersji SOTER MVP zorientowanej na działanie lokalne (local-first), minimalizującej zewnętrzne zależności (brak PostgreSQL, Dockera czy Django w podstawowej ścieżce wykonania).

1. Architektura MVP

Głównym założeniem wersji MVP jest przeniesienie punktu ciężkości z SaaS-a na narzędzie programistyczne i analityczne uruchamiane bezpośrednio na maszynie dewelopera lub architekta.

Główne cechy

Brak serwerów: SOTER nie wymaga działającego demona PostgreSQL, Kùzu czy serwera Django w tle.
Brak kont użytkowników: Cała autoryzacja opiera się na dostępie do lokalnego systemu plików.
Plikowy Ledger: Relacyjna baza SQLite/PostgreSQL została zastąpiona przez niezależny od bazy danych, kryptograficznie weryfikowalny ledger plikowy (append-only).
Wykonanie In-Memory: Walidacja semantyki modeli Logos i ich weryfikacja z faktami odbywa się w pamięci RAM bezpośrednio z plików źródłowych, bez narzutu kompilacji do zewnętrznych plików JSON.

2. Podręcznik CLI (Interfejs Linii Poleceń)

SOTER CLI udostępnia polecenia do walidacji modeli, faktów oraz zarządzania plikowym ledgerem.

2.1. Walidacja Modelu

soter validate [sciezka_do_modelu.model]

Opis: Analizuje model Logos w pamięci (Lark parser, style check/lint, LogosValidator, LogosGraphBuilder).
Wynik: Zwraca status 0 w przypadku powodzenia lub kod błędu i diagnostykę syntaktyczną/semantyczną. Nie generuje żadnych plików wyjściowych na dysku (dry-run).

2.2. Walidacja Faktów i Scenariuszy

soter fact validate [sciezka_do_pliku_lub_katalogu]

Opis: Waliduje poprawność dokumentów faktów (.fact). W przypadku podania katalogu, przeszukuje go rekurencyjnie w poszukiwaniu plików .fact i waliduje je w kolejności leksykograficznej.
Scenariusze: Umożliwia walidację plików opisujących scenariusze (zawierających deklarację element Scenario <nazwa> z listą plików files:). Sprawdza poprawność i istnienie plików w scenariuszu relatywnie do ścieżki scenariusza.
Zakres kontroli:
Poprawność nagłówka (soter v1).
Istnienie wymaganych pól (np. occurred_at w formacie ISO-8601).
Istnienie co najmniej jednego z pól: trigger, action lub type.
Wykrywanie niedozwolonych znaków cudzysłowów drukarskich (Unicode smart quotes “, ”).

2.3. Zarządzanie Ledgerem (`soter ledger`)

Komenda ledger udostępnia zestaw poleceń do kryptograficznego rejestru zdarzeń.

Inicjalizacja ledgera

soter ledger init --org "Nazwa Organizacji" --checkpoint-interval 100

Tworzy strukturę katalogów oraz plik metadanych manifest.ledger.

Rejestracja faktu

soter ledger record <fact_id> <sciezka_do_faktu.fact>

Kopiuje treść faktu do bazy ledgera, przypisuje kolejny numer sekwencyjny (seq), czas rejestracji (recorded_at) oraz generuje powiązania skrótów (hash).

Lista wpisów

soter ledger list

Wyświetla tabelę zarejestrowanych faktów w kolejności sekwencyjnej (Seq, Fact ID, Recorded At, Action/Trigger).

Weryfikacja integralności ledgera

soter ledger verify

Przeprowadza pełny audyt kryptograficzny:

Sprawdza ciągłość sekwencji (od 1, co 1).
Weryfikuje zgodność sumy kontrolnej treści faktu (fact_hash).
Weryfikuje podpis struktury wpisu (entry_hash).
Sprawdza spójność łańcucha (previous_hash bieżącego wpisu musi zgadzać się z entry_hash poprzedniego).

Szczegóły faktu

soter ledger show <fact_id>

Wyświetla pełne metadane wpisu i payload faktu w formacie JSON.

2.4. Weryfikacja Zgodności Modelu z Ledgerem

soter verify --model <sciezka_do_modelu> --ledger <sciezka_do_katalogu_ledgera>

Opis: Ładuje model w pamięci i konfrontuje go z faktami z zapisanego łańcucha ledgera.
Analiza: Sprawdza, czy wywołane akcje/triggery istnieją w modelu, weryfikuje obecność wymaganych wejść (in) oraz zgodność jawnych ograniczeń biznesowych (constraints, np. amount > 0 lub dopuszczalne waluty).

3. Struktura Plikowa Ledgera

Katalog ledgera posiada w pełni czytelną i weryfikowalną strukturę:

ledger_directory/
├── manifest.ledger             # Metadane ledgera, nazwa organizacji, parametry
├── facts/                      # Przechowywanie treści faktów
│   ├── 000000000001.fact
│   └── 000000000002.fact
└── entries/                    # Metadane kryptograficzne wpisów (JSON)
    ├── 000000000001.entry.json
    └── 000000000002.entry.json

Przykładowy plik wpisu (`000000000001.entry.json`)

{
    "ledger_version": "0.1",
    "seq": 1,
    "fact_id": "fact_001",
    "fact_hash": "h-a89f3c...",
    "recorded_at": "2026-07-10T19:12:11Z",
    "previous_hash": "null",
    "entry_hash": "h-f521b3...",
    "source_name": "genesis_payment.fact"
}

4. Konfiguracja Językowa (i18n)

SOTER MVP CLI wspiera dynamiczną lokalizację bez zależności od Django (wspierane języki: en oraz pl).

Priorytet wykrywania języka

Parametr CLI: --lang=pl lub --lang pl.
Zmienna środowiskowa: SOTER_LANG (lub przestarzała SOTER_OUT_LANG).
Plik konfiguracyjny: klucz lang (lub out_lang) w pliku soter.conf.
Ustawienia regionalne systemu operacyjnego (OS locale).
Domyślny język angielski (en).