# Spoločná synchronizácia RAG a GraphRAG

`POST /sync`, overený push webhook aj `python -m tools.rag.rebuild_index`
používajú spoločnú pipeline v `tools/sync_indexes.py`. Obnova vyžaduje dostupné
Neo4j a jeho konfiguráciu v prostredí. Pôvodné evaluačné výsledky sa nemenia.

## Priebeh

1. Procesový `.reindex.lock` pripustí iba jednu synchronizáciu nad data volume.
2. Voliteľný `git pull --ff-only` zachováva pôvodné nastavenie synchronizácie.
3. V `data/.sync-stage-*` vznikne kópia pôvodných README súborov. Dokumenty,
   chunky, SQLite/FTS5 a embeddingy sa pripravujú z tejto jednej kópie. Aktívne
   súbory sa počas prípravy nemenia a existujúce vyhľadávanie môže pokračovať.
4. Overí sa, že sa zdrojové súbory ani Git revízia počas prípravy nezmenili.
5. Pred aktiváciou vzniknú zálohy pôvodných súborov a trvalý marker
   `.sync-pending.json`. Exkluzívny publikačný zámok počká na rozbehnutých
   čitateľov. Nové požiadavky počas aktivácie dostanú dočasnú nedostupnosť.
6. Jedna explicitná Neo4j transakcia odstráni starý spravovaný graf, zapíše
   nový graf a skontroluje počty uzlov/vzťahov oproti pripravenému payloadu.
   Verzia grafu sa zapisuje v tej istej transakcii.
7. Pod publikačným zámkom sa aktivujú pripravené lokálne súbory a potvrdí sa
   grafová transakcia. Po úspechu sa odstráni marker a sprístupní nová verzia.

SQLite a Neo4j netvoria distribuovanú ACID transakciu. Konzistenciu pri tejto
implementácii zaisťujú spoločný zámok pre podporované vyhľadávacie vstupy,
verzie, zálohy a marker nedokončeného prepnutia. Používanie samotného nízkoúrovňového
`search_graph_with_session` mimo publikačnej ochrany je určené pre kontrolované
interné evaluácie/testy; produkčný volajúci používa chránené `search_graph`.

## Verzia a dohľadateľnosť

Každá generácia má identifikátor `version`, Git revíziu zdrojovej wiki,
UTC čas prípravy, hash pôvodných README súborov, hashe dokumentov/chunkov
a názov embeddingového modelu. Hash zdrojov zachytáva aj necommitnuté zmeny;
samotný Git HEAD preto nie je jediným identifikátorom obsahu.

Rovnaký objekt `index_version` je uložený v:

- `data/index_version.json`,
- SQLite tabuľke `index_state`,
- operatívnom uzle Neo4j `IndexState` s ID `zpwiki`.

Operatívny uzol nie je súčasťou znalostného grafu označeného `graph_scope=zpwiki`.
Verziu vracajú `/sync`, webhook, `/health`, RAG vyhľadávanie a verejná Python
funkcia grafového vyhľadávania. Synchronizácia vracia aj `graph_counts`.

## Chyby a zotavenie

- Chyba prípravy, embeddingov alebo nedostupné Neo4j pred aktiváciou:
  pôvodné indexy ostávajú aktívne.
- Chyba pri zápise grafu: celá grafová transakcia sa zruší.
- Chyba pri aktivácii lokálneho súboru: obnovia sa pôvodné súbory a grafová
  transakcia sa zruší. Pri neúspešnej obnove marker zostáva.
- Stratené potvrdenie COMMIT: najprv sa kontroluje skutočná verzia v Neo4j.
  Ak bola nová verzia potvrdená, staré lokálne dáta sa naslepo neobnovujú.
- Pád procesu alebo neoveriteľný výsledok transakcie: marker a obnovovacie
  súbory ostávajú na disku. Vyhľadávanie odmietne nejasný snapshot; RAG API
  vracia 503 a `/health` má `ready=false`.

Po odstránení príčiny spusti znova autorizovaný `/sync` alebo:

```bash
docker compose exec zp-agent-api python -m tools.rag.rebuild_index
```

Úspešná synchronizácia vytvorí kompletnú novú generáciu oboch indexov a marker
odstráni. Marker sa nemá ručne mazať ako náhrada opravy. Staršie adresáre
prerušených behov môžu zostať ako podklady na obnovu; bežný úspešný staging
sa automaticky odstraňuje.

## Samostatná obnova Neo4j

`python -m tools.graphrag.build_graphrag` používa rovnaký transakčný zápis.
Zmena grafu sa potvrdí celá alebo sa zruší celá. Ak JSON vstupy zodpovedajú
aktívnej generácii, jej proveniencia sa zachová. Iné vstupy alebo režim
`--no-replace` nemôžu predstierať synchronizovanú verziu; verejný grafový
vstup potom pri aktívnom manifeste vyžaduje spoločnú synchronizáciu.

## Overenie

Regresie pokrývajú chybu uprostred grafového zápisu, chybu po čiastočnej
aktivácii súborov, stratenú odpoveď COMMIT, neznámy výsledok COMMIT, následné
zotavenie, zámok pre čitateľov, nesúlad verzií, zmenu zdroja počas prípravy,
odpovede `/sync` aj podpísaného webhooku a API 503 pri nejasnej generácii.
Skutočné Neo4j testy overujú rollback po odstránení pôvodných uzlov a zápise
časti náhrady v izolovanom scope. Pozitívny prípad overuje aj opakovateľnosť.

Záverečná sada po dokončení opravy: **464 passed, 4 skipped**. Reálny `/sync`
v Docker API obnovil 114 dokumentov, 887 chunkov a 447 grafových uzlov /
879 vzťahov za 87,72 s. Overené sú rovnaké verzie v manifeste, SQLite, Neo4j,
health, skutočnej RAG odpovedi aj grafovom vyhľadávaní. Obsah znalostného
grafu zodpovedá pôvodnej v4; nové meranie presnosti LLM sa nevykonávalo.
Podrobné overenie: [záznam](synchronizacia_indexov_overenie.json).