KRET LANGUAGE ACADEMY · DOKUMENTACJA ZE ŹRÓDEŁ
Przykłady ze źródeł SDK
Ten sam manifest w SDK i w Kret Engine (Core)
Pełniejszy manifest z sekcjami `environment`, `recovery`, `dependencies`, `runtimeData` i wszystkimi dziewięcioma operacjami cyklu życia. Ten sam projekt jest sprawdzany parserem SDK (`kret check`) i walidatorem referencyjnym Core (`KretCore.Test.exe check`), który dodaje reguły układu hosta (`Disk/`, mapa KretM, jedna generacja manifestu).
VALIDATION_ONLYKretL · BASICNajczęstsze błędy manifestu (tryb ścisły)
Trzy niepoprawne warianty tego samego manifestu, każdy w osobnym folderze: nieznane pole (`KCS-KRL-0202`), uprawnienie spoza katalogu KCS (`KCS-KRL-0206`) i handler cyklu życia, którego nie ma w kodzie (`KCS-KRL-0301`). Folder `valid/` pokazuje wersję poprawną.
VALIDATION_ONLYKretL · BASICPierwszy manifest plugin.kretl
Najmniejszy poprawny manifest KretL 1.0: tożsamość, zgodność, cykl życia (`start` i `shutdown` są obowiązkowe), tryb wykonania. Manifest nie deklaruje żadnych uprawnień, więc plugin nie dostaje dostępu do hosta. Logika jest jedną funkcją KretS zwracającą tekst.
RUNNABLE_LOCALKretL · INTERMEDIATEUprawnienia, komendy hosta, limity i izolacja
Manifest deklaruje uprawnienie wymagane (`logs.own.write`) i opcjonalne (`kretdb.read`), komendę hosta `counter.add`, limity pamięci i CPU, profil `light`, preferowaną izolację `sandbox` oraz deklarację obszaru danych `runtimeData`. Polityka hosta testowego przyznaje tylko `logs.own.write` — deklaracja nie jest przyznaniem.
RUNNABLE_LOCALKretS · ADVANCEDZadania, strumienie i zdarzenia [2.0]
`async fn` i `await` (zadania współbieżne, nie równoległe), `Stream<Int>` z buforem i `for await`, `timeout` obsłużony w `try`/`catch`, deklaracja `event`, handler `on`, `emit` oraz `subscribe … with`.
RUNNABLE_LOCALKretS · ADVANCEDKlasy, interfejsy, dziedziczenie, generyki [2.0]
Interfejs, klasa z konstruktorem `init`, dziedziczenie z `super(...)` i `override`, klasa generyczna `Pair<A, B>`, funkcja generyczna z ograniczeniem `T: Shape`, polimorfizm przez interfejs. Kod bazuje na oficjalnym przykładzie SDK `ObjectOriented`.
RUNNABLE_LOCALKretS · ADVANCEDTesty `kret test` i diagnostyka (EXPERIMENTAL)
Moduły testowe w `Tests/` (funkcje `test…` bez parametrów i bez wyniku). Porażka = `throw`, pominięcie = `throw "SKIP: …"`. `kret test --list` tylko kompiluje i wypisuje plan, `kret test --json` wykonuje każdy moduł w świeżym, izolowanym procesie pluginu. `kret test` ma status EXPERIMENTAL (`kret-test/1`).
RUNNABLE_LOCALKretS · BASICNajczęstsze błędy typów
KretS nie ma konwersji niejawnych. `1 + 2.0` daje `KCS-KRS-0320`, `let x = null` bez typu daje `KCS-KRS-0307`. Folder `fixed/` pokazuje poprawki: jawne `toFloat(1)` i typ `String?`.
VALIDATION_ONLYKretS · BASICPierwszy program KretS
Moduł `Main`, funkcja `Start` zwracająca `String`, zmienna `let`, łączenie tekstów i wpis w dzienniku (`log.info`, wymaga `logs.own.write`).
RUNNABLE_LOCALKretS · INTERMEDIATEPrzetwarzanie danych: rekordy, listy, mapy, błędy
Parsowanie wierszy tekstu do rekordów (`record`), filtrowanie i sumowanie w pętli `for`, grupowanie w `Map<String, Int>`, typy nullable (`parseInt` → `Int64?`, `Map.get` → `V?`) z `orElse`, obsługa błędu `try`/`catch` i `throw`, stała `const`.
RUNNABLE_LOCALKretS · INTERMEDIATEModuły i łączenie funkcji
Jeden plik = jeden moduł. `Main` wywołuje funkcje modułów `Stats` i `Text` przez `Moduł.funkcja`. Rekordy są wspólne dla całego pluginu.
RUNNABLE_LOCALKretDB · ADVANCEDTransakcje, testy `kret test`, odmowy uprawnień i błędy schematu
`db.begin/commit/rollback`, testy KretDB w izolowanym procesie (każdy moduł testowy dostaje świeżą bazę), odmowa zapisu, gdy polityka hosta przyznaje tylko odczyt (`readonly/`), oraz błąd schematu: dwa klucze główne (`bad-schema/`).
RUNNABLE_LOCALKretDB · BASICTrwały licznik (tabela klucz→wartość)
Schemat `Disk/Schema.kdb` z jedną tabelą klucz→wartość. Kod używa `db.getOr` i `db.set`. Dwa uruchomienia z tym samym katalogiem danych pokazują trwałość: drugie uruchomienie widzi wynik pierwszego. Baza należy do brokera — plugin nie widzi SQL ani pliku bazy.
RUNNABLE_LOCALKretDB · INTERMEDIATENazwane zapytania: insert, select, update, delete
Tabela z kolumnami i wartościami domyślnymi, indeks, nazwane zapytania z parametrami (`:id`), sortowanie i limit. Kod KretS dostaje typowane funkcje `db.Add`, `db.Open`, `db.Finish`, `db.Remove`, `db.Count`; wiersz tabeli jest rekordem `tasks`. Komenda hosta `tasks.finish` kończy zadanie.
RUNNABLE_LOCALKretUI · ADVANCEDNotatki: KretUI + KretStyle + KTheme + KretS + KretDB
Pełny przykład warstw interfejsu na podstawie szablonu SDK `multi-language`: struktura (`.kretui`), wygląd (`.kstyle` — selektory, stany, `media`), motyw (`.ktheme` — tokeny, warianty `dark`/`highContrast`, kontrola kontrastu WCAG), logika (KretS) i dane (KretDB). Render w wariancie wysokiego kontrastu i interakcja zapisująca do bazy. Folder `low-contrast/` pokazuje, że zbyt mały kontrast motywu jest błędem kompilacji.
RUNNABLE_LOCALKretUI · BASICPierwszy widok KretUI
Widok `view` z tytułem, stanem (`state`), tekstem z podstawieniem `{licznik}` i przyciskiem, który zmienia stan lokalnie (`set`). Bez logiki KretS — interfejs nie ma żadnych uprawnień. Renderer SDK rysuje prawdziwą klatkę PNG (`--self-test`).
RUNNABLE_LOCALKretUI · INTERMEDIATEFormularz, binding i akcja do KretS
Pole `input` z walidacją (`required`, `maxLength`), akcja `greet` wywołująca komendę KretS `greet.make(name: String) -> String`, wynik zapisywany w stanie (`result`), flaga `busy`, komunikat błędu (`error`) i warunek `enabled "form.valid and not busy"`. Kompilacja sprawdza sygnaturę handlera i blok `handlers` manifestu.
RUNNABLE_LOCALKretFlow · ADVANCEDSynchronizacja kod ⇄ graf i diagnostyka przepływu
`kret flow from-krets … --previous` odtwarza dokument przepływu z kodu KretS, zachowując położenia bloków z poprzedniej wersji (powtórna synchronizacja daje identyczny tekst). Wariant `bad-call/` wywołuje nieistniejącą funkcję — kompilator KretS odrzuca blok `action`.
VALIDATION_ONLYKretFlow · BASICGraf bloków, walidacja i podgląd jako KretS
Przepływ `Flow/Restock.kflow` (format `kretflow-ir/2`, JSON) z szablonu SDK: wyzwalacz, pętla, przypisania, akcja wywołująca funkcję KretS, warunek i koniec. `kret check` sprawdza wyrażenia w blokach kompilatorem KretS, `kret flow to-krets` pokazuje równoważny kod KretS (każdy wiersz oznaczony `// @flow id`), `kret flow blocks` wypisuje katalog bloków (`kretflow-blocks/1`, EXPERIMENTAL).
VALIDATION_ONLYKretFlow · INTERMEDIATEWykonanie przepływu w pluginie (Flow → KretS)
Oficjalna ścieżka wykonania KretFlow: kod KretS wygenerowany z grafu (`kret flow to-krets`) jest modułem `Restock` pluginu, a `Main.Start` go wywołuje. Wykonanie odbywa się w izolowanym procesie pluginu, z tymi samymi uprawnieniami i limitami co każdy kod KretS. Dodatkowo `kret flow run … --module` wykonuje graf w procesie narzędzia (host pozwala tylko na dziennik).
RUNNABLE_LOCALKretAI · ADVANCEDKontrakt narzędzia i polityka danych — błędy
Narzędzie, którego zadeklarowana sygnatura (`amount String`) nie zgadza się z funkcją KretS (`amount: Int`), oraz nieznana polityka danych modelu — obie deklaracje są odrzucane przy kompilacji.
VALIDATION_ONLYKretAI · BASICDeklaracje modelu, narzędzi i agentów
Plik `Ai/assistant.kretai` z szablonu SDK: model lokalny z polityką `local-only`, dwa narzędzia (funkcje KretS z zadeklarowaną sygnaturą i uprawnieniami), dwa agenci z limitami i delegacją. **Model nie jest uruchamiany** — kompilator sprawdza deklaracje, zgodność narzędzi z funkcjami KretS i uprawnienia. Plugin startuje bez AI (zwraca liczbę zamówień z KretDB).
VALIDATION_ONLYKretAI · INTERMEDIATEBramki uprawnień i modelu (bez prawdziwego modelu)
`kret ai ask` pokazuje bramki przed jakimkolwiek połączeniem: bez przyznanych `kretai.use`/`kretai.model.use` → `KCS-KAI-0302`; z przyznaniem, ale bez lokalnego serwera modeli → `KCS-KAI-0301`. Oba wyniki są odmową — żadne dane nie opuszczają komputera.
VALIDATION_ONLYKretLink · BASICKontrakt usługi `.klink`: kompilacja i schemat
Kontrakt `klink "1.0"` z usługą, wersją SemVer, metodami (parametry, wynik, termin, uprawnienie) i typami KretS. `kret link compile` daje postać kanoniczną JSON i skrót SHA-256, `kret link schema` — JSON Schema żądań i wyników (pochodna kontraktu, nie drugie źródło prawdy). Kontrakt **nie daje prawa do komunikacji**.
VALIDATION_ONLYKretLink · INTERMEDIATEBłędy kontraktu i strumienie (EXPERIMENTAL)
Nieznany typ parametru jest błędem kompilacji kontraktu. Metoda `stream` kompiluje się z ostrzeżeniem `KCS-LNK-0121`: transport strumieni jest eksperymentalny (D-KCS-13) i nie należy do kontraktu 1.0.
VALIDATION_ONLYKretM · BASICMapa projektu: warstwy, moduły, mapa lokalna
Szablon SDK `core-plugin`: `project.kretm` (warstwy Ui → Logic → Data, `deny Ui -> Data`, moduły z katalogami, połączenia `link`) i mapa lokalna `Script/Orders/module.kretm`. Manifest włącza mapę blokiem `project { map … }`. KretM **niczego nie przyznaje** — tylko ogranicza zależności.
RUNNABLE_LOCALKretM · INTERMEDIATENaruszenia mapy: warstwy i próba przyznania uprawnień
Wariant `layer-violation/`: moduł warstwy Ui woła moduł warstwy Data mimo `deny Ui -> Data`. Wariant `grant-attempt/`: mapa lokalna próbuje zapisać uprawnienie — `KCS-KRM-0301`.
VALIDATION_ONLYKretLib · ADVANCEDPaczka biblioteki `.klibpkg` i rozstrzyganie wersji
`kret lib pack` tworzy paczkę biblioteki (ZIP z `library.klib` i `Script/**.krs`; tożsamością jest skrót listy plików). `kret lib resolve --update` ponownie rozstrzyga wersje. Paczki bibliotek **nie są podpisywane** (brak podpisów KretLib — ograniczenie SDK).
VALIDATION_ONLYKretLib · BASICBiblioteka offline z plikiem blokady
Szablon SDK `library`: projekt wymaga `mathx` (zakres `>=1.2.0 <2.0.0`), która zależy od `textutil`. Źródłem jest katalog `vendor`, polityka `offline true` i wydawca `local`. `kret lib restore` rozstrzyga wersje i instaluje do `Libs/` (skróty SHA-256 w `project.klibs.lock`), `kret lib list` pokazuje stan. Kod biblioteki działa z uprawnieniami pluginu — biblioteka niczego nie deklaruje.
RUNNABLE_LOCALKretBridge · INTERMEDIATEKretBridge: generacja C# i kontrola wywołań (bez uruchamiania usługi)
Szablon SDK `csharp-bridge`: kontrakt `Bridge/calc.klink`, kod KretS `use Kret.Bridge.demo.calc as calc`. `kret bridge generate` tworzy interfejs C#, a `kret check` sprawdza każde wywołanie `calc.*` względem kontraktu. **Usługa C# nie jest uruchamiana**: KretBridge to PROVISIONAL_VERSIONED, w Core zablokowany (FB-07), a proces usługi nie jest piaskownicą.
VALIDATION_ONLYKretConfig · BASICSchemat ustawień, profile i polityka hosta (PROVISIONAL)
Na podstawie przykładu SDK `ConfigProfiles`: `schema.kconfig` (typy z jednostkami, zakresy, `allowed`, `hotReload`, ustawienie tajne), `project.kconfig` (profile `default`, `gaming extends default`, `quiet`), `policy.kconfig` (blokada i górna granica). `kret config show` składa warstwy i pokazuje pochodzenie każdej wartości; KretS czyta ustawienia przez `Kret.Config`, a sekretu **nie** dostaje.
RUNNABLE_LOCALKretConfig · INTERMEDIATEBłędy konfiguracji: sekret wprost, zakres, polityka w projekcie
Trzy warianty odrzucane przez walidator KretConfig: sekret wpisany wprost (`KCS-CFG-0007`), wartość poza zakresem (`KCS-CFG-0005`) i blok `policy` w pliku projektu (`KCS-CFG-0203`).
VALIDATION_ONLY