DOPORUCENI PRO ZLEPSENI COGNIA PODLE EXPERIMENTU XOR
====================================================

Datum: 31. 7. 2026
Priorita: navrh pro dalsi implementaci

1. SJEDNOTIT FORWARD A GRADIENT HRADLOVANE HRANY (VYSOKA PRIORITA)
-----------------------------------------------------------------

Forward hradlovane hrany pocita:

    contribution = weight * pre_activation * clamp(gate_activation, 0, 1)

Vsechny supervised aktualizace vah musi pouzit stejny efektivni vstup:

    dWeight = error * derivative * pre_activation * gate_activation

Je nutne zkontrolovat obe cesty:

    - supervisedReadoutUpdate (jednokanálovy delta/MSE readout),
    - supervisedSoftmaxReadoutUpdate (softmax/cross-entropy).

Test musi overit, ze zavrene hradlo dava presne nulovou zmenu vahy a otevrene hradlo
stejnou zmenu jako nehradlovana hrana. Pridat regresni test se ctyrmi XOR konjunkcemi
a jedinym vystupem.

2. EXPLICITNI DEKLARACE READOUTU A UCENYCH HRAN (VYSOKA PRIORITA)
---------------------------------------------------------------

Trener dnes odvozuje readout z vrcholove oblasti a topologie. To je nejednoznacne
u mezivrstev, constructu a vice vystupu. Navrh syntaxe:

    output signal from output.result as xor {
        target: scalar;
        loss: mse;
        activation: raw;
        threshold: 0.5;
    }

nebo samostatne:

    training XorTraining {
        objective: supervised;
        features: feature.cells;
        target: output.result;
        loss: mse;
        learn: feature.cells -> output.result;
    }

`plasticity: learnable` musi znamenat, ze hrana smi byt menena supervised trenerem;
`plasticity: none` musi byt vzdy pevna. Trener ma vypsat pocet vybranych ucitelnych
hran a jejich rozsah. Nula ucitelnych hran ma byt chyba, nikoli tichy beh.

3. NATIVNI PRODUKTOVE PRIZNAKY (VYSOKA PRIORITA)
------------------------------------------------

XOR, kontextova gramatika a rizeni vyzaduji konjunkce. Pridat explicitni primitivum,
ktere materializuje produkt jako pojmenovany signal:

    feature xor01 = product(input.a0, input.b1);

nebo construct:

    use construct Product as p(a=input.a0, b=input.b1);

Produkt musi byt dostupny jako bezny endpoint a musi mit shodnou semantiku v CPU,
CUDA forwardu, ukladani site, REST introspekci a supervised gradientu.

4. HLUBOKY CREDIT ASSIGNMENT (STREDNI AZ VYSOKA PRIORITA)
--------------------------------------------------------

Implementovat trenovani alespon pro male dopredne DAG podsite:

    sensory -> fixed/learnable feature -> readout

Minimalni verze nemusi byt obecny autodiff framework. Staci:

    - ulozit aktivace jednotlivych vrstev z forward pruchodu,
    - propagovat delta chybu pres tanh a gate,
    - aktualizovat pouze hrany oznacene `learnable`,
    - zachovat `fixed`, `state` a `derived` beze zmeny,
    - odmitnout cyklus v supervised trenovane casti nebo jej explicitne rozvinout v case.

Pro rekurentni site lze pozdeji pridat truncated BPTT nebo kontrastivni lokalni uceni.

5. BINARNI KLASIFIKACNI VYSTUP (STREDNI PRIORITA)
------------------------------------------------

`output signal` pocita uroven z absolutni aktivace. To neni vhodne pro binarni
klasifikaci, kde znamenko nebo hodnota 0..1 nese tridu. Pridat vystup:

    output binary from output.result as xor {
        threshold: 0.5;
        labels: "0", "1";
    }

REST odpoved:

    {
      "name": "xor",
      "type": "binary",
      "value": 0.6865,
      "class": 1,
      "label": "1",
      "threshold": 0.5
    }

Klient pak nemusi interpretovat surove `output[0]`.

6. PREDZPRACOVANI VSTUPU V COGNIA (STREDNI PRIORITA)
----------------------------------------------------

Nyni PHP provadi prevod `(A,B)` na `[00,01,10,11]`. Pro reprodukovatelnost by mel
byt feature engineering soucasti modelu. Navrh deklarativni transformace:

    source XorInput {
        kind: external;
        publish A : signal;
        publish B : signal;
    }

    encode one_hot_pair from (A, B) as truth_case[4];

REST by potom mohl prijmout `input: [A,B]`, zatimco model sam vytvori priznaky.
Alternativou je obecna podpora cistych vyrazu ve vstupnim adapteru.

7. LEPSI DIAGNOSTIKA TRENINGU (STREDNI PRIORITA)
-----------------------------------------------

Do `cognia_train` pridat:

    - accuracy pro binary output s nastavitelnym prahem,
    - confusion matrix,
    - zmenu vahy (min/max/mean a pocet zmenenych hran),
    - pocet hran vybranych jako readout,
    - varovani pri kolapsu vystupu na konstantu,
    - `--eval-only` pro overeni ulozene site,
    - `--trace-sample N` pro aktivace a efektivni gated features,
    - early stopping podle loss/accuracy,
    - oddeleni trenovaci a validacni mnoziny.

V tomto experimentu by diagnostika okamzite ukazala, ze gated varianta dava temer
konstantni vystup a ze delsi trenovani mezivrstvy zvysuje MSE.

8. DATASET SE SCHEMATEM A JMÉNY (NIZSI AZ STREDNI PRIORITA)
----------------------------------------------------------

Soucasny format `cognia-dataset 4 1` nepopisuje vyznam sloupcu. Navrh v2:

    cognia-dataset "2.0" {
        input: [case00, case01, case10, case11];
        target: [xor];
        task: binary_classification;
        threshold: 0.5;
    }

Nasleduji numericke radky. Trener muze overit shodu jmen a rozmeru s modelem a
REST `_model` muze publikovat stejne schema.

9. INTEGRACNI TEST TRAIN -> SAVE -> SERVE -> EVALUATE (VYSOKA PRIORITA)
---------------------------------------------------------------------

Pridat automaticky test, ktery:

    1. naparsuje XOR model,
    2. natrénuje jej s pevnym seedem,
    3. overi accuracy 4/4,
    4. ulozi `.bin`,
    5. spusti `cognia_serve` na loopback a nahodnem volnem portu,
    6. zavola vsechny ctyri vstupy pres `/evaluate`,
    7. overi stejne vysledky po reloadu,
    8. server korektne ukonci a smaze docasny artefakt.

Tento test pokryje parser, topology builder, CUDA runtime, trener, serializaci i REST.

10. DOPORUCENE PORADI IMPLEMENTACE
----------------------------------

    Krok 1: opravit a otestovat `pre * gate` v delta/MSE aktualizaci.
    Krok 2: pridat vypis/validaci ucitelnych readout hran.
    Krok 3: pridat `output binary` a REST reprezentaci.
    Krok 4: materializovane `product` feature jako endpoint.
    Krok 5: integracni XOR test s raw vstupem `[A,B]`.
    Krok 6: explicitni training blok a omezeny deep credit assignment.
    Krok 7: dataset schema v2 a deklarativni input transformace.

AKCEPTACNI CIL
--------------

Po implementaci ma jit napsat model, ktery prijima primo dva senzory `[A,B]`,
vytvori konjunkce uvnitr Cognia, natrénuje se bez PHP feature engineeringu a po
ulozeni/nacteni vrati pres REST vsechny ctyri XOR pripady spravne. PHP ma pouze
odeslat `[A,B]` a vypsat deklarovany binary output.
