# Atlas API — tracker silników i bibliotek Atlas łączy snapshoty oryginalnych DLL z rejestracjami `MethodSpec` w Rex-EMoolator. Nie uruchamia emulatora ani binarek. Nie utożsamia wykrycia metody z poprawną implementacją. ## Uruchomienie Z katalogu tego repozytorium, z zainstalowanymi zależnościami `.[api]`: ```sh .venv/bin/python -m ams.serve_tracker \ --emulator-root /ścieżka/do/Rex-EMoolator ``` Otwórz `http://127.0.0.1:8766/ui/tracker.html`. Command Center ma odnośnik do Atlasu. `GET /tracker` oraz `GET /tracker?download=1` udostępniają te same dane jako JSON. Snapshoty z bazy i jawnie wskazanego katalogu są łączone i deduplikowane po SHA DLL. Bez SHA używany jest identyfikator snapshotu, jawnie niebędący tożsamością binarki. Katalog snapshotów jest przeszukiwany rekurencyjnie. Wyniki batcha mają pierwszeństwo przed starszymi snapshotami tego samego SHA; konflikt jest widoczny w uwagach, a dane nie są automatycznie scalane. Launcher domyślnie wczytuje `data/binary-inventory.json`, aby pokazać pokrycie zbioru DLL. Filtr rodziny i wariantu ogranicza dowody oryginału; nadal pokazuje sumę metod API z oznaczeniem „nieustalone” dla braku obserwacji w wybranym zakresie. Eksport bez serwera: ```sh .venv/bin/python -m ams.tracker snapshots/batch/*.snapshot.json snapshots/*.snapshot.json \ --emulator-root /ścieżka/do/Rex-EMoolator \ --reviews tracker-reviews.json --out /tmp/tracker.json ``` Atlas odczytuje snapshoty z dysku przy każdym pobraniu katalogu. Command Center, diff i eksport zgodności korzystają z bazy SQLite; nowe wyniki można do niej dodać poleceniem `.venv/bin/python -m ams.api.importer snapshots/batch/*.snapshot.json`. ## Interpretacja - **Zarejestrowana**: znaleziono wpis `MethodSpec`, bez oceny poprawności. - **Podejrzenie stubu**: heurystyka wykryła wyjątek lub komunikat o braku implementacji. Może dotyczyć tylko gałęzi; wymaga przeglądu. - **Brak rejestracji**: adapter nie znalazł wpisu; dynamiczny dispatcher może obsługiwać metodę inaczej. - **Zaimplementowana / przegląd ASM / test zachowania**: aktualne deklaracje przeglądu obejmują wszystkie obserwowane warianty danej pary typ/metoda. - **Nieustalone w oryginale**: brak obserwacji, nigdy dowód nieobecności. Licznik to pary typ/metoda. Nie jest liczbą unikalnych ciał Java ani procentem zgodności całego silnika. Metody bazowe `CMC_Runner` (SEND, CLONE, …) są w zakresie `*` raz; typy wskazują go polem `inherits`. Zakres `@` to instrukcje `@IF`/`@LOOP`/… (runner typu 0), porównywane z `CodeParser.dispatchSpecialCall`. Typy bez rozpoznanych metod pozostają widoczne. Typ → runner pochodzi z `runner_map` snapshotu (fabryka w 7.1+, konstruktory klas w 6.1); bez niego z nazwy klasy, oznaczone jako wnioskowane. Metoda wspólnego runnera, którą oryginał pomija dla danego typu warunkiem `obj.getType()`, nie jest temu typowi przypisana; pusta implementacja wirtualna jest oznaczona jako brak efektu. Sygnatury (typy argumentów i wyniku) są odczytane z ciała metody i mogą być sumą wariantów (`int/string`). Eventy typu pochodzą z jego vtable (`type_events`) albo z listy najbliższej klasy w łańcuchu konstruktorów. Po stronie emulatora liczy się literał nazwy: w klasie typu (`emitted`), w `Variable.java` (`emitted_base`), w innym kodzie bez przypisania do typu (`engine_literal`); `not_found` znaczy tylko, że literału nie ma. Pola typu pochodzą z jego łańcucha konstruktorów (`type_fields`) albo z pól jego klasy i jej baz. Po stronie emulatora: klucz `":NAME"` w gałęzi typu w `CNVParser.createVariable` lub odczyt atrybutu (`getAttribute`, `getAttributeInHierarchy`, `attributes().get`) w klasie typu (`read`), w `Variable.java` (`read_base`), gdzie indziej (`engine_literal`). Alias `BOOL` jest łączony z `BOOLEAN`, `INT` z `INTEGER`; nazwy metod są normalizowane do uppercase. ID metody pozostaje lokalne dla konkretnej klasy i binarki. Relacje dziedziczenia pochodzą wyłącznie ze snapshotu, nie są zgadywane z innej wersji. Adapter rozpoznaje bieżący wzorzec rejestracji Java; nie jest ogólnym parserem języka Java. Komentarze i literały nie tworzą fałszywych wpisów, nawiasy są dopasowywane leksykalnie. Własne dispatchery `GROUP` / `INSTANCE` są oznaczone do przeglądu. Celowe no-op nie są automatycznie stubami. ## Dowody poprawności `tracker-reviews.json` jest wersjonowanym rejestrem przeglądów; początkowo pustym. Ekstrakcja rejestracji silników, WORLD i KOLOROWANKA nie wypełnia go automatycznie. Każdy wpis wymaga pól tekstowych: | Pole | Znaczenie | |---|---| | `type`, `method` | Para API | | `binary_sha256`, `rva` | Dokładna binarka i adres względny, np. `0xc950` | | `emulator_commit`, `body_sha256`, `source_tree_sha256` | Rewizja i hashe z eksportu trackera | | `kind` | `asm` lub `runtime` | | `verdict` | `matches`, `partial`, `differs` | | `reviewer`, `date` | Autor i data przeglądu | | `notes`, `evidence` | Zakres porównania i odnośnik do trwałego dowodu/testu | `matches` oznacza świadomą ocenę całej metody dla wskazanego wariantu; dla sprawdzenia pojedynczego przypadku użyj `partial`. Sam adres lub dekompilat nie wystarcza do takiej oceny. Zmiana commita lub dowolnego źródła Java w `core/src` unieważnia przegląd konserwatywnie (także zmiana helpera). Można zachować historyczne wpisy dla starszych rewizji. Sprzeczne, zduplikowane przeglądy tej samej pary i rewizji są odrzucane. Adresy `impl_addr`, `case_addr`, `registration_addr` w snapshotach są VA, nie RVA. Należy odjąć potwierdzoną bazę obrazu przed zapisaniem `rva`. ## Kolejka dalszej analizy ```sh .venv/bin/python -m ams.inventory /ścieżka/do/_dll_repository \ /ścieżka/do/World.dll /ścieżka/do/Kolorowanka.dll \ --snapshots snapshots --out /tmp/binary-inventory.json ``` Manifest zachowuje wszystkie ścieżki identycznych DLL i proponuje pliki wynikowe po pełnym SHA. Nie uruchamia analiz. Klasyfikacja nazw wymaga przeglądu przy przemianowanych DLL. Starsze Pikliby są wyłączone z zakresu, Sekai oznaczone jako zależność natywna. Kolejka wszystkich unikalnych silników: [batch.md](batch.md). Statyczne dowody pluginów: [WORLD](world-analysis.md) i [KOLOROWANKA](kolorowanka-pilot.md). Pozostałe etapy: uogólnienie ekstrakcji pluginów na kolejne warianty; uzupełnienie niepełnych mapowań klas, dziedziczenia, pól i zdarzeń; rozstrzygnięcie podwójnej rejestracji WORLD.SETPOSITION; analiza natywnego Sekai; porównanie zachowania i rejestracja przeglądów. Historyczny snapshot 7.1 bez SHA pozostaje oznaczony jako nieustalony; nowe ekstrakcje mają pełną tożsamość DLL. Istniejący ogólny pipeline `acquire(directory)` nadal wybiera jeden silnik — do masowej analizy służy `ams.acquire.batch`.