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:
co-authored by
Claude Opus 5.5
parent
b0013c5114
commit
10c81c4390
@@ -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`.
|
||||
Reference in New Issue
Block a user