feat(tracker): Atlas joining DLL snapshots with emulator registrations

Matches original script APIs against MethodSpec registrations in
Rex-EMoolator and keeps review evidence separate from registration.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Patryk Gensch
2026-10-24 18:24:15 +02:00
co-authored by Claude Opus 5.5
parent b0013c5114
commit 10c81c4390
13 changed files with 846 additions and 1 deletions
+75
View File
@@ -0,0 +1,75 @@
# 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, z rozwinięciem rozpoznanego dziedziczenia. Nie jest liczbą unikalnych ciał Java ani procentem zgodności całego silnika. Zakres `*` pokazuje metody bazowe/globalne; nazwy klas bez dopasowania fabryki są wnioskowane (mogą obejmować klasy bazowe i singletony). Typy bez rozpoznanych metod pozostają widoczne.
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`.