Manual

Podręcznik Logos (Symbiotic Ontology Transformations Enterprise Runtime)

Logos to język dziedzinowy (DSL) służący do modelowania architektury przedsiębiorstwa i procesów biznesowych. Niniejszy dokument opisuje składnię wersji v1.

Pełna specyfikacja ontologii i filozofii: → CONTEXT_BOOTSTRAP_FILE.md

1. Podstawowa Struktura Pliku

Każdy plik modelu zaczyna się od deklaracji wersji:

soter v1

Opcjonalnie pod nagłówkiem może pojawić się komentarz provenance (hash commitu):

soter v1
# soter commit: a1b2c3d4 pass

Komentarze

# Komentarz jednolinijkowy

'''
Komentarz
wielolinijkowy (blokowy)
'''

2. Elementy — Ontologia Triady

Elementy są węzłami grafu. Każdy musi mieć type z oficjalnej triady SOTER.

Składnia

element u-550e8400-e29b-41d4-a716-446655440000()
    type: Subject
    name: "Przyjazna Nazwa"
    name@pl: "Nazwa po polsku"
    description: "Opis elementu"

Identyfikatory (UUID) zawsze noszą prefiks u-. UUID są automatycznie generowane i wstrzykiwane przez pipeline przy pierwszym uruchomieniu — nie wpisuj ich ręcznie.

Dozwolone typy (`type`)

Typ	Rola	Odpowiednik w byłej ontologii
`Subject`	Aktywny aktor: firma, dział, osoba, system IT	`Unit`, `Role`, `System`
`Action`	Atom transformacji — niepodzielna funkcja wejście→wyjście	`Activity` (atom)
`Activity`	Modekuła/Proces — zbiera podmioty/akcje w logiczną całość	`Activity` (jako proces)
`Object`	Pasywny zasób: materia, energia, pamięć (dane)	`DataArtifact`, `DataStore`

Podkategorie `Object` (`category`)

Kategoria	Definicja	Przykłady medium
`energy`	Zasób zużywalny (zanik po użyciu)	PLN, kWh, Paliwo
`matter`	Substrat fizyczny budulcowy	Stal, Drewno, Paleta
`memory`	Informacja kopiowalna bez strat	PDF, SQL_Record, Email

Podkategorie `Subject` (`autonomy`)

autonomy: true → Suwerenny system (BPMN: Pool)
autonomy: false → Zależny komponent (BPMN: Lane)

Wymagane atrybuty funkcjonalne (Strict Mode)

Action: intent (cel), from, to, in (wejście), out (wyjście)
Subject: role (definicja użyteczności), autonomy (Sprawstwo/Poziom bytu)
Object: category (energy | matter | memory)

3. Relacje i Bramki

Składnia Relacji (blokowa)

relationship u-a1b2c3d4-0001-0001-0001-000000000010()
    source: u-<UUID-podmiotu>
    target: u-<UUID-akcji>
    carries: u-<UUID-obiektu>

Typy relacji:

source / target — relacja asymetryczna (hierarchia, przepływ)
member — relacja symetryczna (asocjacja, zespół)

Bramki (Gateways)

gateway u-a1b2c3d4-0001-0001-0001-000000000011()
    name: "Czy zaakceptowano?"
    type: XOR

Typy bramek: XOR (alternatywa), OR (opcje), AND (wszystkie).

4. Modułowość

Include

include "models/enterprise.model"
include "models/finance.model"

Ścieżki są relatywne do pliku bazowego. System automatycznie wykrywa i blokuje zapętlenia (Circular Includes).

Pliki .model nie mogą includować plików .view. Pliki .view mogą includować pliki .model.

Show

show u-<UUID-elementu>

Decyduje, który element (i jego powiązania) zostanie wyrenderowany na diagramie.

5. Aliasy — Dopasowanie do Domeny

Logos obsługuje aliasy użytkownika do dopasowania terminologii do domeny:

soter v1
alias Subject as Pracownik
alias Action as Zadanie

element u-abc123()
    type: Pracownik
    name: "Jan Kowalski"

Strict Mode: Wbudowane skróty kluczowych słów (rel, el, gw, t) są niedostępne w strict mode. Używaj pełnych słów kluczowych (relationship, element, gateway, type). Jedynym mechanizmem skracania jest alias X as Y.

6. Rozszerzenia BPMN (Mapowanie Ontologiczne)

Renderer D2 automatycznie mapuje typy elementów na standardowe kształty:

Mapowanie Elementów

Typ BPMN	Wartość `type:`	Kształt D2
Zdarzenie Start	`Start`	Koło (zielone)
Zdarzenie End	`End`	Koło (pogrubione, czerwone)
Zadanie	`Task`, `UserTask`	Prostokąt
Baza danych	`Database`	Cylinder
Basen (Pool)	Subject + `autonomy: true`	Kontener
Tor (Lane)	Subject + `autonomy: false`	Kontener wewnętrzny

Widoki BPMN (`.view`)

view "Dashboard_Finansowy"
    source: "models/firma.model"
    focus:
        category: energy
    render:
        mapping: BPMN_2_0
        aggregate_by: intent

7. Pliki Ledger (`.fact`)

Pliki .fact to niezmienny dziennik zdarzeń (Append-only Ledger). Pełna specyfikacja: → doc/02_spec/LedgerSpec.md (planned)

Składnia bloku `fact`

fact f-001
    occurred_at: 2026-03-08T09:00:00
    trigger: u-<UUID-akcji>
    consume:
        u-<UUID-obiektu>: { amount: 10, cost_basis: 2000 PLN }
    produce:
        u-<UUID-obiektu>: { cost_basis: 1800 PLN }

Kluczowe atrybuty

Atrybut	Opis
`occurred_at`	Czas deklarowany przez źródło (subiektywny)
`recorded_at`	Czas obiektywnego zapisu (nadawany przez Obserwatora)
`trigger`	UUID Akcji z `.model`, która wyzwoliła zdarzenie
`consume`	Zużyte zasoby (Object) z ilościami i wartościami
`produce`	Wytworzone zasoby z wartościami
`corrects`	ID wcześniejszego błędnego faktu (korekta immutable)
`type: logical_compensation`	Fakt dorozumiany wygenerowany przez Reconcilera

8. Warstwa Operacyjna (`.interaction`)

Pliki .interaction stanowią dedykowaną warstwę obsługującą operacje zapisu dokonywane przez użytkowników w interfejsie Hollow Client.

Zasada 001 Lintera: Komponenty operacyjne (np. wyzwalacze zdarzeń/przyciski jak SubmitButton, wagi sprzętowe, formularze ActionForm) są surowo wzbronione w widokach analitycznych (.view). Muszą zostać oddzielone i zamodelowane w plikach .interaction.

8. Przykłady

Przykład 1: Minimal — „Hello World"

soter v1

element u-abc00001()
    type: Subject
    name: "Moja Firma"
    autonomy: true
    role: "Operator rynku"

show u-abc00001

Przykład 2: Struktura Organizacyjna

soter v1

element u-abc00001()
    type: Subject
    name: "Globalna Korporacja"
    autonomy: true
    role: "Centrum decyzyjne"

element u-abc00002()
    type: Subject
    name: "Dział IT"
    autonomy: false
    role: "Dostawca usług technologicznych"

relationship u-abc00010()
    source: u-abc00001
    target: u-abc00002

show u-abc00001

Przykład 3: Proces z Zasobem

soter v1

element u-abc00001()
    type: Subject
    name: "Klient"
    autonomy: true
    role: "Inicjator zamówienia"

element u-abc00002()
    type: Object
    name: "Środki finansowe"
    category: energy
    nature: financial
    medium: PLN

element u-abc00003()
    type: Action
    name: "Opłacenie faktury"
    intent: "Regulacja zobowiązania"
    in: u-abc00002
    out: u-abc00004

relationship u-abc00010()
    source: u-abc00001
    target: u-abc00003

show u-abc00003

10. SOTER Epiphany — Poziomy i Interfejs

SOTER Epiphany (interfejs WWW) wspiera progresywne odkrywanie funkcji poprzez system poziomów zaawansowania oraz tryb chroniony dla wdrożeń produkcyjnych.

Poziomy Implementacji (Levels 1-4)

Możesz kontrolować złożoność interfejsu za pomocą parametru implementation_level w soter.conf.

Level 1 (Podstawowy): Widoczne tylko kluczowe moduły: Modele, Widoki, Wyniki (Results), Ustawienia oraz GitSync. Idealny dla początkujących architektów.
Level 2 (Analityczny): Dodaje moduł Workflows (Przepływy — d. Kanban) oraz Fakty (.fact).
Level 3 (Operacyjny): Dodaje moduł Interakcje (.interaction) do modelowania warstwy UI Hollow Client.
Level 4 (Pełny): Wszystkie funkcje platformy są widoczne.

Tryb Chroniony (Protected Mode)

W środowisku produkcyjnym (SOTER_ENV=production), Epiphany działa w trybie chronionym:

Niezalogowani użytkownicy widzą tylko stronę Home (README.md) oraz link do logowania.
Menu nawigacyjne jest ukryte do momentu autoryzacji.
Wszystkie wrażliwe opcje konfiguracji w "Ustawieniach" są ukryte.

Przeglądarka Baz Danych i Zapytania

Moduły "Logs", "Databases" i "Queries" zostały przeniesione do bardziej intuicyjnych miejsc:

Wyniki (Results): Tutaj znajdziesz surowe logi (.log) oraz pliki baz danych.
Przeglądarka DB: Kliknięcie w plik .sqlite3 lub .kuzu otwiera zaawansowany edytor, który pozwala na:
Podgląd tabel i grafów.
Uruchamianie zapytań SQL/Cypher.
Zapisane Zapytania: Lista Twoich plików .sql/.cypher jest dostępna bezpośrednio w pasku bocznym przeglądarki bazy danych.

11. Dobre Praktyki

UUID: Nie wpisuj UUID ręcznie — SOTER generuje i wstrzykuje je automatycznie.
Modularność: Trzymaj ontologię firmy w enterprise.model, procesy w osobnych plikach.
Wcięcia: Atrybuty wewnątrz elementu MUSZĄ być wcięte 4 spacjami. Brak tabulatorów.
Kolejność atrybutów: type → name → atrybuty funkcjonalne → metadane. Linter egzekwuje tę kolejność.
Strict Mode: Każda Action wymaga dodatkowo from oraz to. Subject wymaga autonomy.