Schemat i trwały licznik

KretDB — wprowadzenie

Status 1.0: `FROZEN_SUPPORTED_SUBSET` — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0. Gramatyka/wersja: kretdb-1.0. Status języka nie nadaje uprawnień KCS ani prawa do działania w Production.

Czym jest

KretDB to własny interfejs bazy danych pluginu: schemat w Disk/Schema.kdb, nazwane zapytania typowane względem KretS, transakcje, izolowana baza należąca do brokera (backend SQLite — decyzja R-11). Plugin nigdy nie widzi SQL ani uchwytu bazy.

Dla początkujących

Opisujesz tabele (kolumny i typy) oraz nazwane zapytania („dodaj zadanie”, „pokaż otwarte”). W KretS wołasz je jak funkcje: db.Add(1, "tytuł"). Proste pary klucz→wartość obsługujesz przez db.get/set. Dane zostają między uruchomieniami.

Dla zaawansowanych programistów

Zapytanie jest strukturą danych; SqlBuilder tworzy SQL wyłącznie z identyfikatorów sprawdzonych wzorcem i wiąże każdą wartość (sqlite3_bind_*). Wynik select deterministyczny (klucz główny rozstrzyga remisy), limit 10 000 wierszy. Niezatwierdzona transakcja jest wycofywana przez brokera. maxSize tabeli liczony w bajtach wartości. Właściciel bazy = tożsamość pluginu (w Core dodatkowo SID, KretProfileID, InstallationID, wydawca, digest). Migracja schematu, kopia i odtwarzanie istnieją w SDK, ale w Core są PROVISIONAL. SFI-B01: odmowa autoryzacji w transakcji → wycofanie (zwykły błąd skryptu nie wycofuje).

Jakie problemy rozwiązuje

Trwałe dane pluginu bez SQL injection, bez dostępu do cudzych baz i bez wycieku uchwytów; spójność przez transakcje; przewidywalne wyniki.

Kiedy używać

• notatnik, zadania, ustawienia lokalne pluginu
• liczniki i historia operacji
• pamięć agenta KretAI
• dane prezentowane w KretUI

Kiedy nie używać

• złączenia tabel, agregacje inne niż liczba wierszy, zapytania składane z tekstu (nie istnieją)
• porównania kolumn Decimal/Bytes w where (KCS-KDB-0102)
• dostęp do bazy z C# pluginu (tylko zaufany adapter Core / KretBridge)
• produkcyjne użycie w Core przed decyzją D-KCS-01 (kretdb.* PROVISIONAL)

Współpraca z innymi technologiami

KretS (use Kret.DB as db), KretL (kretdb.open/read/write, runtimeData.database), KretUI (dane przez komendy KretS), KretAI (pamięć agenta), Core (Disk/ = przestrzeń KretDB).

Obecny status

FROZEN_SUPPORTED_SUBSET — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0.

Dalej: ARCHITECTURE.md · SYNTAX_REFERENCE.md · ../Tutorials/BASIC/TUTORIAL_PL.md

KretDB — referencja składni

Status 1.0: `FROZEN_SUPPORTED_SUBSET` — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0. Gramatyka/wersja: kretdb-1.0. Status języka nie nadaje uprawnień KCS ani prawa do działania w Production.

Opisane są wyłącznie konstrukcje potwierdzone implementacją SDK (i, gdzie zaznaczono, testami tej rundy).

database / version

Baza pluginu i wersja schematu.

1database Tasks {
2    version = 1
3}

table / column / primary key / default / index

Tabela z kolumnami, kluczem głównym, domyślnymi wartościami i indeksem.

1table tasks {
2    id: Int primary key
3    title: String
4    done: Bool default false
5    index by title
6}

storage { mode maxSize }

Tryb przechowywania i limit bajtów wartości tabeli.

1storage {
2    mode = "persistent"
3    maxSize = 4MB
4}

query … select

Nazwane zapytanie odczytu.

1query Open() -> List<tasks> {
2    select tasks where done == false sort by id desc limit 100
3}

query … insert / update / delete

Nazwane zapytania zapisu.

1query Add(id: Int, title: String) -> Unit {
2    insert into tasks { id = :id, title = :title }
3}
4query Finish(id: Int) -> Int {
5    update tasks set done = true where id == :id
6}

db.get / getOr / set / delete / exists

Operacje na tabeli klucz→wartość (klucz + jedna kolumna).

1let n = db.getOr("counters", "runs", 0) + 1
2db.set("counters", "runs", n)

db.begin / commit / rollback

Transakcja; niezatwierdzona do końca handlera jest wycofywana.

1db.begin()
2db.set("balance", "a", 70)
3db.commit()

migration from N (SDK; Core PROVISIONAL)

Krok danych przy przejściu wersji schematu; wykonuje go wyłącznie zaufany host.

1migration from 1 {
2    update tasks set done = false where done == null
3}

KretDB — samouczek BASIC

Status 1.0: `FROZEN_SUPPORTED_SUBSET` — zamrożony dokładnie opisany zakres; reszta poza kontraktem 1.0. Gramatyka/wersja: kretdb-1.0. Status języka nie nadaje uprawnień KCS ani prawa do działania w Production.

Cel: pierwszy plik, podstawowa struktura, najprostszy działający przykład, najczęstszy błąd, sposób uruchomienia.

Narzędzia: kret = <SDK>\Compiler\kret.exe (SDK 1.0.0-rc.3+kret.local.3), kretui-host = <SDK>\UiHost\kretui-host.exe. {DATA}/{OUT} = nowe, puste katalogi.

1. Trwały licznik (tabela klucz→wartość) (KRETDB-B01-PersistentCounter)

Projekt: ../../Examples/BASIC_PersistentCounter/ · klasyfikacja RUNNABLE_LOCAL · Playground LOCAL_EXECUTE

Kroki (katalog roboczy: katalog przykładu):

1. kret check . --json — w wyniku: "succeeded": true
2. kret run . --policy host-policy.json --data {DATA} — w wyniku: uruchomienie nr 1
3. kret run . --policy host-policy.json --data {DATA} — w wyniku: uruchomienie nr 2

Wynik tej rundy: PASS — zob. EXPECTED_OUTPUT.txt.