MyDemoBot

How the Zig-backed instance graph works (GraphView/NodeReference/EdgeReference), the real Python API surface, and the invariants around allocation, attributes, and cleanup.

1. Zaimportuj GraphView z modułu faebryk.core.graph — to główny punkt wejścia do pracy z grafem. GraphView to widok na członkostwo i sąsiedztwo węzłów przechowywanych w Zig.

2. Utwórz instancję grafu za pomocą GraphView.create() — nigdy nie wywoływaj konstruktora bezpośrednio. Zwrócony obiekt GraphView zawiera areny, mapy i bitsets potrzebne do operacji na grafie.

3. Pracuj z węzłami i krawędziami poprzez NodeReference i EdgeReference — są to uchwyty wartościowe (UUID) wskazujące na globalny backing storage w Zig. Używaj metod fabrycznych takich jak NodeReference.create(**attrs) zamiast konstruktorów.

4. Pamiętaj o niezmiennikach: nie modyfikuj referencji bezpośrednio, nie obchodź alokacji, nie ignoruj czyszczenia. Węzły i krawędzie muszą być tworzone i usuwane poprzez GraphView.

5. Zawsze wywoływaj g.destroy() na koniec pracy — najlepiej w bloku finally, aby upewnić się, że zasoby Zig zostaną zwolnione nawet w przypadku wyjątku.

6. Jeśli budujesz system traversujący graf (np. compiler lub wizualizacja), używaj BoundNode i BoundEdge jako wrapperów — łączą referencję z wskaźnikiem do posiadającego GraphView, co ułatwia nawigację.