Files
Aidem-Media-DLL-Analysis/docs/tracker.md
T
Patryk GenschandClaude Opus 5.5 aee8f17417 feat: type_fields in diff and tracker, joined with emulator property reads
The tracker lists each scope's original properties (constructor chain,
or class fields up the chain for Piklib 6.1 and singletons such as
SCENE) and where the emulator reads them: a CNVParser.createVariable
case arm, an attribute read in the type's class or Variable.java, or
other code. The switch-arm parser is shared with the @ statements.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-24 20:30:36 +02:00

79 lines
6.7 KiB
Markdown

# 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`.