docs: record the first correct in-race frame rate

Measured on both hosts, with the method and the reason a median is the wrong
statistic for the Pixel 6a (bimodal 60/30 - the median sits in the upper lobe
and reports 59.8 where the mean is 39.5).

Also retires the old "51 fps" from task #61: it was not measured in a race
and is not comparable. That is the second time a figure from elsewhere in the
game was nearly quoted as in-race performance, so it is written down plainly.

The consequence is a priority change - the 6a misses the frame budget by a few
percent, so #63 and #64 are worth more than their profile shares suggest, and
the hot path has very little margin left to spend on new work.

Co-Authored-By: Claude <noreply@anthropic.com>

.gitignore

@@ -13,3 +13,39 @@
 .externalNativeBuild
 .cxx
 local.properties
+
+# IDA databases - 148MB for libapp.so.i64 alone, and regenerable from the .so
+*.i64
+*.id0
+*.id1
+*.nam
+*.til
+# trace_agent is built by its own build.sh, outside Gradle
+trace_agent/build/
+# ostream_repro likewise - CMake/ninja output, the sources next to it are kept
+ostream_repro/build/
+# ad-hoc device capture logs
+device_run_*.log
+
+# Where `gradlew assembleTranslatedRelease` output was collected by hand for
+# signing. 611 MB of signed APK - a build product, and one that carries the
+# bundled OBB with it, so it must never reach history.
+app/translated/
+
+# Release signing material never belongs in the repo - see app/build.gradle.kts
+*.jks
+*.keystore
+keystore.properties
+*-release.properties
+
+# Bundled game data (~595 MB). A build INPUT, not source: it is the game's own
+# OBB, copied into assets so the APK self-extracts it on first launch (see
+# GameDataInstaller.kt). Keeping it out of history on purpose - a 595 MB blob
+# is rejected outright by most hosts, and once committed it can only be removed
+# by rewriting history.
+#
+# To build: copy the OBB here yourself, under exactly this name.
+#   cp main.<versionCode>.<package>.obb app/src/main/assets/game_data.obb
+# Without it the app still builds and runs; it just expects the OBB to already
+# be on the device at getObbDir(), the way it was before this was bundled.
+app/src/main/assets/game_data.obb

.idea/deploymentTargetSelector.xml

@@ -2,15 +2,24 @@
 <project version="4">
   <component name="deploymentTargetSelector">
     <selectionStates>
+      <SelectionState runConfigName="savemanager">
+        <option name="selectionMode" value="DROPDOWN" />
+        <DialogSelection />
+      </SelectionState>
       <SelectionState runConfigName="app">
         <option name="selectionMode" value="DROPDOWN" />
-        <DropdownSelection timestamp="2025-08-28T12:35:54.649730307Z">
-          <Target type="DEFAULT_BOOT">
-            <handle>
-              <DeviceId pluginId="PhysicalDevice" identifier="serial=2B101JEGR07875" />
-            </handle>
-          </Target>
-        </DropdownSelection>
+        <DialogSelection />
+      </SelectionState>
+      <SelectionState runConfigName="main">
+        <option name="selectionMode" value="DROPDOWN" />
+        <DialogSelection />
+      </SelectionState>
+      <SelectionState runConfigName="unitTest">
+        <option name="selectionMode" value="DROPDOWN" />
+        <DialogSelection />
+      </SelectionState>
+      <SelectionState runConfigName="androidTest">
+        <option name="selectionMode" value="DROPDOWN" />
         <DialogSelection />
       </SelectionState>
       <SelectionState runConfigName="main">

app/build.gradle.kts

@@ -1,3 +1,8 @@
+// Inside the android { } block the name `java` resolves to Gradle's own
+// java extension and shadows the package, so these types have to be
+// imported here rather than fully qualified at the use site.
+import java.util.Properties
+
 plugins {
     alias(libs.plugins.android.application)
     alias(libs.plugins.kotlin.android)
@@ -5,22 +10,78 @@ plugins {
 }
 
 android {
-    namespace = "com.ea.games.nfs13_mod"
+    // ARM64-only-device prototype (see /ARM64_TRANSLATION_LAYER.md): "_arm"
+    // instead of "_mod" so this build can be installed side by side with
+    // the real armeabi-v7a mod, not overwrite it.
+    namespace = "com.ea.games.nfs13_arm"
     compileSdk = 35
 
     defaultConfig {
-        applicationId = "com.ea.games.nfs13_mod"
+        applicationId = "com.ea.games.nfs13_arm"
         minSdk = 27
         targetSdk = 35
         versionCode = 1003128
         versionName = "1.3.128"
 
-        ndk.abiFilters.add("armeabi-v7a")
-        //ndk.abiFilters.add("x86")
+        // mpcore is now plain native ARM64 code driving an embedded ARM32
+        // CPU-emulation core - no armeabi-v7a native code is built/shipped
+        // for this app at all.
+        ndk.abiFilters.add("arm64-v8a")
+        // x86_64 (2026-09-22): lets the translated build install in WayDroid,
+        // whose Android image is x86_64. Unicorn picks its tcg/i386 backend
+        // there automatically, so the ARM32 guest is translated by US rather
+        // than by houdini - which is what made earlier WayDroid attempts with
+        // the native ARM build unreliable.
+        //
+        // NOTE: the flat guest mapping (task #61, worth 1.24x) is implemented
+        // only in tcg/aarch64, so an x86_64 host silently falls back to the
+        // software MMU and will be slower. Fine for a test target; port the
+        // same change into tcg/i386 if it ever becomes a shipping target.
+        ndk.abiFilters.add("x86_64")
+
+        // Default: false. Overridden to true by the "native32" flavor - see
+        // its own comment below.
+        buildConfigField("boolean", "NATIVE32", "false")
 
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
     }
-    ndkVersion = "21.0.6113669"
+    ndkVersion = "27.0.12077973"
+
+    // Release signing. The keystore and its password live OUTSIDE this repo
+    // (~/keystores/), deliberately: this is a git working tree, and a signing
+    // identity that can be committed eventually is committed. Gradle reads
+    // them from a properties file if it is there, and falls back to the debug
+    // key if it is not - so a checkout without the key still builds, it just
+    // produces something that cannot be shipped.
+    //
+    // To create the key (once, and then back it up - losing it means never
+    // being able to update an installed build):
+    //
+    //   keytool -genkeypair -v -keystore ~/keystores/nfsmw-release.jks \
+    //     -alias nfsmw -keyalg RSA -keysize 4096 -validity 10950
+    //
+    // then write ~/keystores/nfsmw-release.properties with:
+    //   storeFile=/home/<you>/keystores/nfsmw-release.jks
+    //   storePassword=...
+    //   keyAlias=nfsmw
+    //   keyPassword=...
+    signingConfigs {
+        val releaseProps = File(System.getProperty("user.home"), "keystores/nfsmw-release.properties")
+        if (releaseProps.isFile) {
+            val props = Properties().apply { releaseProps.inputStream().use { load(it) } }
+            create("release") {
+                storeFile = file(props.getProperty("storeFile"))
+                storePassword = props.getProperty("storePassword")
+                keyAlias = props.getProperty("keyAlias")
+                keyPassword = props.getProperty("keyPassword")
+                // Both modern signature schemes: v2 covers the whole APK and
+                // is what Android 7+ verifies, v3 allows rotating the key
+                // later without invalidating existing installs.
+                enableV2Signing = true
+                enableV3Signing = true
+            }
+        }
+    }
 
     buildTypes {
         release {
@@ -29,6 +90,28 @@ android {
                 getDefaultProguardFile("proguard-android-optimize.txt"),
                 "proguard-rules.pro"
             )
+            // Local-testing-only (2026-09-05, "why is this ~100x slower than
+            // native" investigation - see ARM64_TRANSLATION_LAYER.md): no
+            // real release signing config exists in this prototype, and
+            // there's no intent to ship this build anywhere - reusing the
+            // auto-generated debug keystore just makes `assembleTranslatedRelease`
+            // installable on a test device the same way translatedDebug
+            // already is. The actual point of testing this build type is the
+            // NATIVE side (mpcore's CMakeLists.txt now forces
+            // CMAKE_BUILD_TYPE=RelWithDebInfo unconditionally, so this
+            // isn't even required for that fix to take effect - it's here so
+            // this variant can be installed at all for a genuine debuggable=false
+            // comparison, e.g. CheckJNI's behavior).
+            // Real key when it exists, debug key otherwise. Announced at
+            // configuration time rather than discovered later from a
+            // mysteriously unshippable APK.
+            signingConfig = signingConfigs.findByName("release") ?: run {
+                logger.warn(
+                    "RELEASE SIGNING: ~/keystores/nfsmw-release.properties not found - " +
+                    "signing with the DEBUG key. This APK must NOT be distributed."
+                )
+                signingConfigs.getByName("debug")
+            }
         }
     }
     compileOptions {
@@ -38,8 +121,88 @@ android {
     kotlinOptions {
         jvmTarget = "11"
     }
+    androidResources {
+        // The bundled game data (assets/game_data.obb, ~595 MB) is an already
+        // compressed archive - deflating it again would cost a long build and
+        // a slower install for no size gain, and it must stay STORED so it can
+        // be streamed straight out of the APK.
+        noCompress += "obb"
+    }
+
     buildFeatures {
         compose = true
+        buildConfig = true
+    }
+
+    // "native32" flavor - diagnostic-only reference build for the native
+    // ARM32 tracing investigation (see ARM64_TRANSLATION_LAYER.md /
+    // sorted-popping-plum.md's "Native ARM32 tracing harness" plan). Real
+    // armeabi-v7a support and a BuildConfig.NATIVE32 flag GameActivityMain
+    // uses to load the real, unmodified native libraries directly
+    // (System.loadLibrary) instead of going through mpcore's emulation path
+    // - only meaningful on genuinely 32-bit-capable hardware (the Galaxy
+    // A9), never intended to ship. MUST be armeabi-v7a-ONLY (not just
+    // "armeabi-v7a added alongside arm64-v8a") - confirmed live on-device
+    // that shipping both ABIs makes Android launch the process via the
+    // 64-bit app_process64/Zygote (arm64-v8a is present, so it's preferred),
+    // which can never dlopen/LD_PRELOAD a 32-bit .so at all (a process's
+    // bitness is fixed for its whole lifetime, not per-library) - defeats
+    // the entire point of this flavor. ndk.abiFilters.clear() first,
+    // since AGP's per-flavor abiFilters otherwise ADD to defaultConfig's
+    // set rather than replace it.
+    flavorDimensions += "abi"
+    productFlavors {
+        create("translated") {
+            dimension = "abi"
+            // Default/existing behavior - the emulated arm64-v8a path,
+            // unchanged from before this flavor split existed.
+        }
+        create("native32") {
+            dimension = "abi"
+            ndk.abiFilters.clear()
+            ndk.abiFilters.add("armeabi-v7a")
+            buildConfigField("boolean", "NATIVE32", "true")
+        }
+    }
+
+    // 2026-09-16 (ARM64_TRANSLATION_LAYER.md - trace_agent wrap.sh deployment):
+    // manually injecting a bundled wrap.sh into the packaged native32 APK
+    // (AGP's own native-lib merge/strip pipeline only recognizes *.so files
+    // and silently drops anything else) failed to install at all with
+    // "Failed to extract native libraries, res=-2" under the default
+    // extractNativeLibs=false packaging - PackageManager validates every
+    // entry under lib/<abi>/ as a loadable library when it plans to mmap
+    // straight from the APK, and a plain shell script fails that check.
+    // Legacy (extracted-to-disk) packaging doesn't do that same strict
+    // validation. Only applied to native32 - the translated flavor doesn't
+    // need or want this (slightly larger install, marginally slower first
+    // native-lib load).
+    productFlavors.getByName("native32") {
+        packaging {
+            jniLibs {
+                useLegacyPackaging = true
+            }
+        }
+    }
+}
+
+// 2026-09-06 (native32-on-real-hardware launch investigation - see
+// ARM64_TRANSLATION_LAYER.md): ndk.abiFilters above only restricts THIS
+// module's own native code - the "native32" flavor still needs `mpcore` on
+// the compile classpath (GameActivityMain.kt's shared, non-flavor-specific
+// source calls mpcore functions in its non-NATIVE32 branch), and mpcore's
+// own CMakeLists always builds arm64-v8a regardless of which app flavor
+// pulls it in. That arm64-v8a .so was silently merged into the native32
+// APK too, so a real device with both an arm64-v8a AND an armeabi-v7a lib
+// present chose to launch the process as 64-bit (app_process64) - which can
+// never load this flavor's 32-bit fmodex/fmodevent/Nimble/app libraries at
+// all, confirmed live via `UnsatisfiedLinkError: couldn't find "libfmodex.so"`
+// (nativeLibraryDirectories only listed arm64/arm64-v8a paths). Explicitly
+// drop every arm64-v8a .so from the native32 variant's packaging so the
+// APK is genuinely armeabi-v7a-only, restoring 32-bit process selection.
+androidComponents {
+    onVariants(selector().withFlavor("abi" to "native32")) { variant ->
+        variant.packaging.jniLibs.excludes.add("lib/arm64-v8a/*.so")
     }
 }
 

app/src/androidTest/java/com/ea/games/nfs13_arm/ExampleInstrumentedTest.kt

@@ -1,4 +1,4 @@
-package com.ea.games.nfs13_mod
+package com.ea.games.nfs13_arm
 
 import androidx.test.platform.app.InstrumentationRegistry
 import androidx.test.ext.junit.runners.AndroidJUnit4
@@ -19,6 +19,6 @@ class ExampleInstrumentedTest {
     fun useAppContext() {
         // Context of the app under test.
         val appContext = InstrumentationRegistry.getInstrumentation().targetContext
-        assertEquals("com.ea.games.nfs13_mod", appContext.packageName)
+        assertEquals("com.ea.games.nfs13_arm", appContext.packageName)
     }
 }

app/src/main/AndroidManifest.xml

@@ -26,6 +26,7 @@
 
     <uses-configuration android:reqTouchScreen="finger"/>
     <application
+        android:name="nfs.mod.traceagent.TraceApplication"
         android:theme="@style/Theme.AppCompat.NoActionBar"
         android:label="@string/app_name"
         android:icon="@mipmap/adaptive_icon"
@@ -48,6 +49,34 @@
                 android:value="bar"/>
         </activity>
 
+        <!-- One-time unpack of the game data bundled in the APK. -->
+        <activity
+            android:name="com.ea.ironmonkey.GameDataUnpackActivity"
+            android:exported="false"
+            android:excludeFromRecents="true"
+            android:label="Подготовка данных" />
+
+        <!-- Shown on the launch after a crash, never during one - a signal
+             handler cannot start an Activity (see crash_handler.cpp). -->
+        <activity
+            android:name="com.ea.ironmonkey.CrashReportActivity"
+            android:exported="false"
+            android:excludeFromRecents="true"
+            android:label="Crash report" />
+
+        <!-- Lets the tester share the zip. Required: targetSdk 35 rejects
+             file:// URIs in ACTION_SEND. Grants access to the crash directory
+             only, and only for the duration of the send. -->
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.crashreports"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/crash_report_paths" />
+        </provider>
+
         <activity
             android:exported="true"
             android:name="com.ea.ironmonkey.PermissionsActivity"

app/src/main/java/com/ea/ironmonkey/CrashReportActivity.kt

@@ -0,0 +1,237 @@
+package com.ea.ironmonkey
+
+import android.content.Intent
+import android.os.Build
+import android.os.Bundle
+import android.util.Log
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.Button
+import androidx.compose.material3.Card
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import androidx.core.content.FileProvider
+import java.io.File
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.zip.ZipEntry
+import java.util.zip.ZipOutputStream
+
+/**
+ * Shown on the launch AFTER a crash, never during one.
+ *
+ * The native handler (crash_handler.cpp) can only write a file - a signal
+ * handler runs on an already-broken process where JNI and Activities are not
+ * legal. So it drops `crash_pending.txt` and dies; this screen is what the
+ * tester sees next time they open the game.
+ *
+ * Everything it produces stays on the device unless the tester presses send.
+ * There is no backend and no automatic upload - see BETA_TELEMETRY_PLAN.md.
+ *
+ * Built with Compose/Material3 and its own dark colour scheme rather than the
+ * game's `Theme.AppCompat.NoActionBar`: this screen must render correctly no
+ * matter what the rest of the app's theming does, and it is the one screen a
+ * tester sees when everything else has already gone wrong.
+ */
+class CrashReportActivity : ComponentActivity() {
+
+    companion object {
+        private const val TAG = "CrashReport"
+        private const val PENDING_NAME = "crash_pending.txt"
+
+        /** Reports live here: Android/data/<pkg>/files/crashes - reachable over USB, no permission needed. */
+        fun crashDir(activity: android.app.Activity): File =
+            File(activity.getExternalFilesDir(null), "crashes")
+
+        /** The file the native handler writes. Null if there is nothing waiting. */
+        fun pendingReport(activity: android.app.Activity): File? =
+            File(crashDir(activity), PENDING_NAME).takeIf { it.isFile && it.length() > 0 }
+    }
+
+    private var bundle: File? = null
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        // Android 15 draws every app edge to edge whether it asks or not, so
+        // the choice is between handling insets or having text sit under the
+        // status bar. Declaring it explicitly and letting Scaffold apply the
+        // padding is the supported way; the first version did neither and the
+        // content ran under the system bars.
+        enableEdgeToEdge()
+        super.onCreate(savedInstanceState)
+
+        val pending = pendingReport(this)
+        if (pending == null) {
+            // Nothing to report - never block the tester on an empty screen.
+            finish()
+            return
+        }
+
+        // Rename out of the way FIRST, before anything that could fail. The
+        // native handler always writes the same fixed name (it cannot safely
+        // format a timestamp inside a signal handler), so leaving it in place
+        // would let the next crash overwrite a report not yet sent.
+        val stamp = SimpleDateFormat("yyyyMMdd-HHmmss", Locale.US).format(Date())
+        val kept = File(crashDir(this), "crash-$stamp.txt")
+        if (!pending.renameTo(kept)) {
+            Log.w(TAG, "could not rename $pending - reporting it in place")
+        }
+        val report = if (kept.isFile) kept else pending
+
+        val details = buildString {
+            append(deviceSummary())
+            append("\n\n")
+            append(runCatching { report.readText() }.getOrElse { "(could not read the report: $it)" })
+        }
+        bundle = runCatching { zipReport(report, details, stamp) }
+            .onFailure { Log.w(TAG, "could not build the zip", it) }
+            .getOrNull()
+
+        setContent {
+            MaterialTheme(colorScheme = darkColorScheme()) {
+                CrashReportScreen(
+                    details = details,
+                    bundlePath = bundle?.absolutePath,
+                    canSend = bundle != null,
+                    onSend = ::share,
+                    onContinue = ::startGame,
+                )
+            }
+        }
+    }
+
+    private fun deviceSummary(): String = buildString {
+        append("device: ${Build.MANUFACTURER} ${Build.MODEL}\n")
+        append("android: ${Build.VERSION.RELEASE} (API ${Build.VERSION.SDK_INT})\n")
+        append("soc: ${Build.HARDWARE}\n")
+        append("abis: ${Build.SUPPORTED_ABIS.joinToString(", ")}\n")
+        append("app: ${appVersion()}")
+    }
+
+    private fun appVersion(): String = runCatching {
+        val p = packageManager.getPackageInfo(packageName, 0)
+        "${p.versionName} (${p.longVersionCode})"
+    }.getOrElse { "(unknown)" }
+
+    private fun zipReport(report: File, details: String, stamp: String): File {
+        val out = File(crashDir(this), "crash-$stamp.zip")
+        ZipOutputStream(out.outputStream().buffered()).use { zip ->
+            zip.putNextEntry(ZipEntry("crash.txt"))
+            zip.write(details.toByteArray())
+            zip.closeEntry()
+            if (report.isFile) {
+                zip.putNextEntry(ZipEntry(report.name))
+                report.inputStream().use { it.copyTo(zip) }
+                zip.closeEntry()
+            }
+        }
+        return out
+    }
+
+    private fun share() {
+        val file = bundle ?: return
+        val uri = runCatching {
+            FileProvider.getUriForFile(this, "$packageName.crashreports", file)
+        }.getOrElse {
+            Log.w(TAG, "FileProvider failed for $file", it)
+            return
+        }
+        val send = Intent(Intent.ACTION_SEND).apply {
+            type = "application/zip"
+            putExtra(Intent.EXTRA_STREAM, uri)
+            putExtra(Intent.EXTRA_SUBJECT, "NFSMW arm64 - отчёт о сбое")
+            addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
+        }
+        startActivity(Intent.createChooser(send, "Отправить отчёт"))
+    }
+
+    private fun startGame() {
+        startActivity(Intent(this, GameActivityMain::class.java))
+        finish()
+    }
+}
+
+@Composable
+private fun CrashReportScreen(
+    details: String,
+    bundlePath: String?,
+    canSend: Boolean,
+    onSend: () -> Unit,
+    onContinue: () -> Unit,
+) {
+    // Scaffold's innerPadding carries the system-bar insets, so nothing ends up
+    // under the status bar or the gesture handle.
+    Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .padding(innerPadding)
+                .padding(16.dp)
+        ) {
+            Text(
+                text = "Игра аварийно завершилась",
+                style = MaterialTheme.typography.headlineSmall,
+            )
+            Text(
+                // Say plainly what is in the file before offering to send it.
+                // The tester is the one sending it; they should know what it
+                // contains.
+                text = "Отчёт сохранён на устройстве. В нём модель телефона, версия Android, " +
+                        "версия сборки и технические данные о сбое. Личных данных и игрового " +
+                        "аккаунта в нём нет.",
+                style = MaterialTheme.typography.bodyMedium,
+                modifier = Modifier.padding(top = 8.dp),
+            )
+            if (bundlePath != null) {
+                Text(
+                    text = bundlePath,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    modifier = Modifier.padding(top = 8.dp),
+                )
+            }
+
+            Card(modifier = Modifier
+                .fillMaxWidth()
+                .padding(top = 16.dp)
+                .weight(1f)
+            ) {
+                Text(
+                    text = details,
+                    fontSize = 11.sp,
+                    lineHeight = 15.sp,
+                    modifier = Modifier
+                        .verticalScroll(rememberScrollState())
+                        .padding(12.dp),
+                )
+            }
+
+            Row(
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .padding(top = 16.dp),
+                horizontalArrangement = Arrangement.spacedBy(8.dp, Alignment.End),
+            ) {
+                OutlinedButton(onClick = onContinue) { Text("Продолжить") }
+                Button(onClick = onSend, enabled = canSend) { Text("Отправить отчёт") }
+            }
+        }
+    }
+}

app/src/main/java/com/ea/ironmonkey/GameActivityMain.kt

@@ -41,6 +41,7 @@ import com.ea.nimble.Global
 import nfs.mod.mpcore.DebugFeatures
 import nfs.mod.mpcore.GameInput
 import nfs.mod.mpcore.MultiplayerCore.loadCore
+import nfs.mod.mpcore.MultiplayerCore.loadEmulatedLibapp
 import nfs.mod.mpcore.SyntheticInputDispatcher
 import org.fmod.FMODAudioDevice
 import java.io.File
@@ -51,6 +52,9 @@ import java.util.concurrent.TimeUnit
 import javax.microedition.khronos.egl.EGLConfig
 import javax.microedition.khronos.opengles.GL10
 import androidx.core.net.toUri
+import androidx.core.view.WindowCompat
+import androidx.core.view.WindowInsetsCompat
+import androidx.core.view.WindowInsetsControllerCompat
 import com.ea.ironmonkey.domain.FSNode
 import org.apache.http.BuildConfig
 import kotlin.system.exitProcess
@@ -77,9 +81,24 @@ class GameActivityMain : AppCompatActivity(), DrawFrameListener {
     private var isSleepModeEnabled = true
     private var mRotation = 0
 
+    // nativeRestoreContext() is a real native call that can block for a
+    // long time (on the current emulated engine, indefinitely - see
+    // ARM64_TRANSLATION_LAYER.md's render-stall root cause: it transitively
+    // reaches NimbleWrapper::InitNimble(), which gets stuck polling an
+    // empty directory). Real hardware keeps this kind of init work off the
+    // GLThread entirely (confirmed via a native trace comparison - the
+    // real device's own version-check activity and its GL calls run on two
+    // separate OS threads). Dispatched to its own background thread here so
+    // onDrawFrame - which MUST keep running every frame to keep rendering -
+    // never blocks on it, instead of calling it synchronously every frame
+    // like the original code did.
+    @Volatile private var restoreContextThreadStarted = false
+    @Volatile private var restoreContextDone = false
+    @Volatile private var restoreContextResult = false
+
     // cont.44 DEBUG: fires MultiplayerCore.triggerCarSelectTest() on
     // demand via `adb shell am broadcast -a nfs.mod.mpcore.TEST_OPEN_CARSELECT
-    // -p com.ea.games.nfs13_mod` - stands in for a future real lobby-overlay
+    // -p com.ea.games.nfs13_arm` - stands in for a future real lobby-overlay
     // "select car" button, letting the on-demand car_select-opening call be
     // exercised at an arbitrary moment (not just automatically at boot) for
     // live testing. See PROGRESS.md cont.44.
@@ -101,8 +120,9 @@ class GameActivityMain : AppCompatActivity(), DrawFrameListener {
 
     // cont.48 DEBUG: fires the EXPERIMENTAL true-direct-jump variant via
     // `adb shell am broadcast -a nfs.mod.mpcore.TEST_TRUE_DIRECT_CARSELECT
-    // -p com.ea.games.nfs13_mod`. See PROGRESS.md cont.48. See cont.78 above
-    // for why this is wrapped in queueEvent.
+    // -p com.ea.games.nfs13_arm` (nfs13_mod on the native32/launcher build -
+    // same trigger, different package id per build flavor). See PROGRESS.md
+    // cont.48, and cont.78 above for why this is wrapped in queueEvent.
     private val trueDirectCarSelectTestReceiver = object : android.content.BroadcastReceiver() {
         override fun onReceive(context: android.content.Context?, intent: Intent?) {
             gameGLSurfaceView.queueEvent { nfs.mod.mpcore.MultiplayerCore.triggerTrueDirectCarSelectJump() }
@@ -112,7 +132,19 @@ class GameActivityMain : AppCompatActivity(), DrawFrameListener {
     private fun updateRequestedOrientation(i: Int) {
     }
 
-    fun IsSystemKey(i: Int) = false
+    // Keys the SYSTEM must handle, not the game.
+    //
+    // This used to be a flat `= false`, which combined with the callers'
+    // `return !IsSystemKey(keyCode)` meant the activity claimed EVERY key it
+    // ever saw - including volume. That is why changing the volume needed the
+    // notification shade: the keys were being swallowed before Android could
+    // act on them.
+    fun IsSystemKey(i: Int) = when (i) {
+        KeyEvent.KEYCODE_VOLUME_UP,
+        KeyEvent.KEYCODE_VOLUME_DOWN,
+        KeyEvent.KEYCODE_VOLUME_MUTE -> true
+        else -> false
+    }
 
     companion object {
         private const val DOWNLOAD_PROPERTIES = "downloadcontent/config.properties"
@@ -168,11 +200,36 @@ class GameActivityMain : AppCompatActivity(), DrawFrameListener {
     }
 
     fun useAssetsFileSystem(): Boolean {
-        return mAssetLocationType != AssetLocationType.EXTERNAL
+        val result = mAssetLocationType != AssetLocationType.EXTERNAL
+        d(TAG, "useAssetsFileSystem() called, mAssetLocationType=$mAssetLocationType, result=$result, thread=${Thread.currentThread().name}")
+        return result
     }
 
     external fun nativeOnCreate()
 
+    /**
+     * Hooks the fatal signals so a native crash leaves a report behind. Must be
+     * called AFTER loadCore(); see its call site.
+     */
+    private fun installNativeCrashHandler() {
+        try {
+            val dir = java.io.File(getExternalFilesDir(null), "crashes")
+            val info = packageManager.getPackageInfo(packageName, 0)
+            nativeInstallCrashHandler(
+                dir.absolutePath,
+                "${info.versionName} (${info.longVersionCode}) ${Build.MANUFACTURER} ${Build.MODEL} " +
+                        "Android ${Build.VERSION.RELEASE}"
+            )
+        } catch (e: Throwable) {
+            // Diagnostics must never stop the game from starting - but say so,
+            // otherwise "no crash reports" looks like "no crashes".
+            i(TAG, "installNativeCrashHandler FAILED - native crashes will go unreported: $e")
+        }
+    }
+
+    /** See crash_handler.cpp. Writes to `dir`; `buildStamp` goes at the top of every report. */
+    external fun nativeInstallCrashHandler(dir: String, buildStamp: String)
+
     external fun nativeOnDestroy()
 
     external fun nativeOnMusicPlayerStateChanged()
@@ -211,6 +268,13 @@ class GameActivityMain : AppCompatActivity(), DrawFrameListener {
 
         i(TAG, "onCreate")
         super.onCreate(bundle)
+
+        // Volume keys should move the MUSIC stream - the one the game actually
+        // plays through - rather than whatever Android would pick by default.
+        volumeControlStream = AudioManager.STREAM_MUSIC
+
+        applyImmersiveMode()
+
         
        
         handler = Handler()
@@ -256,14 +320,18 @@ class GameActivityMain : AppCompatActivity(), DrawFrameListener {
         i(TAG, "onCreate() isMusicActive = $isAnyMusicPlaying")
         mFMODAudioDevice = FMODAudioDevice()
 
+        d(TAG, "obb.size check: mAssetLocationType before = $mAssetLocationType")
         if (mAssetLocationType != AssetLocationType.ASSETS) {
             try {
                 val open2 = getResources().assets.open("obb.size")
                 mAssetLocationType = AssetLocationType.OBB
                 open2.close()
+                d(TAG, "obb.size check: opened OK, mAssetLocationType now OBB")
             } catch (e2: IOException) {
-                Log.e(TAG, e2.message!!)
+                Log.e(TAG, "obb.size check FAILED: " + e2.message)
             }
+        } else {
+            d(TAG, "obb.size check: skipped, already ASSETS")
         }
         val sensorManager = getSystemService(SENSOR_SERVICE) as SensorManager
         val defaultSensor = sensorManager.getDefaultSensor(1)
@@ -299,12 +367,39 @@ class GameActivityMain : AppCompatActivity(), DrawFrameListener {
             mFrameLayout.addView(buildDebugMenuOverlay())
         }
         setContentView(mFrameLayout)
-        System.loadLibrary("fmodex")
-        System.loadLibrary("fmodevent")
-        System.loadLibrary("c++_shared")
-        System.loadLibrary(Global.NIMBLE_ID)
-        System.loadLibrary("app")
-        loadCore()
+        // ARM64-only-device prototype (see /ARM64_TRANSLATION_LAYER.md):
+        // fmodex/fmodevent/Nimble/app are all armeabi-v7a-only builds (no
+        // arm64-v8a .so shipped for any of them, confirmed this session -
+        // see jniLibs/) - System.loadLibrary() for them would throw
+        // UnsatisfiedLinkError immediately on an arm64-v8a-only APK. libapp.so
+        // is loaded through mpcore's embedded ARM32 emulation core instead
+        // (see loadCore() below); FMOD/Nimble audio and the real game
+        // render/boot loop are NOT bridged yet - this build proves the
+        // emulation-core load+hook mechanism, not a running game.
+        //
+        // BuildConfig.NATIVE32 (the "native32" Gradle flavor - see
+        // app/build.gradle.kts and the native-arm32-trace-harness plan in
+        // ARM64_TRANSLATION_LAYER.md) restores the ORIGINAL, real loading
+        // path instead: on genuinely 32-bit-capable hardware (the Galaxy
+        // A9), load the real, unmodified armeabi-v7a libraries directly, no
+        // emulation involved - the ground-truth reference build for that
+        // investigation. Never true for the normal (translated) flavor.
+        if (com.ea.games.nfs13_arm.BuildConfig.NATIVE32) {
+            System.loadLibrary("fmodex")
+            System.loadLibrary("fmodevent")
+            System.loadLibrary("c++_shared")
+            System.loadLibrary(Global.NIMBLE_ID)
+            System.loadLibrary("app")
+        } else {
+            loadCore()
+            // Immediately after loadCore(), and not a line earlier: this is
+            // the first moment libmpcore.so is loaded, so it is the first
+            // moment the native symbol exists. Installing it up in onCreate's
+            // opening lines threw UnsatisfiedLinkError, silently leaving every
+            // crash unreported.
+            installNativeCrashHandler()
+            loadEmulatedLibappFromAssets()
+        }
         // RECEIVER_EXPORTED: needs to be reachable from an external `adb
         // shell am broadcast` sender (there's no in-app sender for this
         // debug-only trigger), and ContextCompat handles the API 33+
@@ -325,6 +420,42 @@ class GameActivityMain : AppCompatActivity(), DrawFrameListener {
         nativeOnCreate()
     }
 
+    // ARM64-only-device prototype (see /ARM64_TRANSLATION_LAYER.md): copies
+    // the bundled armeabi-v7a libapp.so (assets/native_probe/libapp.so - a
+    // raw asset, not jniLibs, since this app declares only arm64-v8a) to a
+    // real file the first time, then hands mpcore's embedded ARM32
+    // emulation core the path. Idempotent - skips the copy if the file
+    // already exists with a plausible size.
+    private fun loadEmulatedLibappFromAssets() {
+        val outFile = File(filesDir, "libapp_armeabi_v7a.so")
+        try {
+            if (!outFile.exists() || outFile.length() < 1_000_000L) {
+                assets.open("native_probe/libapp.so").use { input ->
+                    outFile.outputStream().use { output -> input.copyTo(output) }
+                }
+                d(TAG, "loadEmulatedLibappFromAssets: extracted asset to " + outFile.absolutePath)
+            }
+            // The game's own ARM32 FMOD (task #67). Shipped as raw assets for the
+            // same reason libapp.so is: this APK declares only arm64-v8a, so
+            // jniLibs/armeabi-v7a is never packaged. The engine loads them as
+            // secondary guest images so libapp's FMOD imports reach real code
+            // instead of fmod_shims.cpp's no-ops.
+            for (lib in arrayOf("libfmodex.so", "libfmodevent.so")) {
+                val f = File(filesDir, lib)
+                if (!f.exists() || f.length() < 1_000L) {
+                    assets.open("native_probe/" + lib).use { input ->
+                        f.outputStream().use { output -> input.copyTo(output) }
+                    }
+                    d(TAG, "loadEmulatedLibappFromAssets: extracted " + f.absolutePath)
+                }
+            }
+            val ok = loadEmulatedLibapp(outFile.absolutePath)
+            d(TAG, "loadEmulatedLibappFromAssets: loadEmulatedLibapp -> " + ok)
+        } catch (e: IOException) {
+            d(TAG, "loadEmulatedLibappFromAssets: failed to extract/load asset: " + e)
+        }
+    }
+
     fun forEach(input: String?): Array<String?> {
         return arrayOf<String?>(input)
     }
@@ -521,6 +652,10 @@ class GameActivityMain : AppCompatActivity(), DrawFrameListener {
 
     override fun onKeyDown(keyCode: Int, keyEvent: KeyEvent): Boolean {
         super.onKeyDown(keyCode, keyEvent)
+        // Checked BEFORE the state gate on purpose: the gate returns true for
+        // every key whenever the game is not in STATE_GAME_START, which would
+        // otherwise keep swallowing volume through the whole load.
+        if (IsSystemKey(keyCode)) return false
         if (state != 8) {
             return true
         }
@@ -536,6 +671,7 @@ class GameActivityMain : AppCompatActivity(), DrawFrameListener {
 
     override fun onKeyUp(i: Int, keyEvent: KeyEvent): Boolean {
         super.onKeyUp(i, keyEvent)
+        if (IsSystemKey(i)) return false
         if (state != 8) {
             return true
         }
@@ -563,7 +699,28 @@ class GameActivityMain : AppCompatActivity(), DrawFrameListener {
         }
     }
 
+    /**
+     * Hides the status and navigation bars for the duration of the game.
+     *
+     * Nothing did this before, which is why the navigation bar sat on top of
+     * the game. TRANSIENT_BARS_BY_SWIPE keeps them reachable - a swipe from the
+     * edge brings them back temporarily - so this hides the bars without taking
+     * the system away from the player.
+     *
+     * Must be re-applied on every focus gain: Android restores the bars after a
+     * dialog, the shade, or a task switch, and a one-shot call in onCreate
+     * silently stops working the first time any of those happens.
+     */
+    private fun applyImmersiveMode() {
+        WindowCompat.setDecorFitsSystemWindows(window, false)
+        WindowInsetsControllerCompat(window, window.decorView).apply {
+            hide(WindowInsetsCompat.Type.systemBars())
+            systemBarsBehavior = WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
+        }
+    }
+
     override fun onWindowFocusChanged(z: Boolean) {
+        if (z) applyImmersiveMode()
         super.onWindowFocusChanged(z)
         i(TAG, "onWindowsFocusChanged($z) state=$state")
         getGameGLSurfaceView().renderMode = if (z) 1 else 0
@@ -753,9 +910,9 @@ class GameActivityMain : AppCompatActivity(), DrawFrameListener {
     override fun onDrawFrame(gl10: GL10?) {
         var inputStream: InputStream?
         var shouldCleanupSplash = false
-        Log.d("state::game", "onDrawFrame state=$state")
         // Логирование изменения состояния
         if (state != laststate) {
+            Log.d("state::game", "onDrawFrame state=$state")
             Log.d(TAG, "onDrawFrame state=$state")
             laststate = state
         }
@@ -789,12 +946,24 @@ class GameActivityMain : AppCompatActivity(), DrawFrameListener {
             }
 
             STATE_GAME_START -> {
-                if (splashTimer < System.currentTimeMillis() && nativeRestoreContext()) {
-                    isAssetsReady = true
-                    nativeOnStart()
-                    nativeOnResume()
-                    gameRenderer.setDrawFrameListener(null)
-                    shouldCleanupSplash = true
+                if (splashTimer < System.currentTimeMillis()) {
+                    if (!restoreContextThreadStarted) {
+                        restoreContextThreadStarted = true
+                        d(TAG, "nativeRestoreContext: starting background thread from tid=" + Thread.currentThread().id)
+                        Thread {
+                            d(TAG, "nativeRestoreContext: background thread running, tid=" + Thread.currentThread().id)
+                            restoreContextResult = nativeRestoreContext()
+                            restoreContextDone = true
+                            d(TAG, "nativeRestoreContext: background thread finished, result=$restoreContextResult")
+                        }.apply { isDaemon = true }.start()
+                    }
+                    if (restoreContextDone && restoreContextResult) {
+                        isAssetsReady = true
+                        nativeOnStart()
+                        nativeOnResume()
+                        gameRenderer.setDrawFrameListener(null)
+                        shouldCleanupSplash = true
+                    }
                 }
             }
         }

app/src/main/java/com/ea/ironmonkey/GameDataInstaller.kt

@@ -0,0 +1,129 @@
+package com.ea.ironmonkey
+
+import android.content.Context
+import android.util.Log
+import java.io.File
+
+/**
+ * Unpacks the game data bundled inside the APK to the place the game expects.
+ *
+ * The ~595 MB archive ships as `assets/game_data.obb`, stored uncompressed
+ * (see `noCompress` in build.gradle.kts - it is already a compressed archive,
+ * so deflating it again would only cost build and install time). On first
+ * launch it is copied to `getObbDir()/main.<versionCode>.<package>.obb`, which
+ * is exactly the path `GameActivityMain.obbFullPath` builds, so nothing else in
+ * the game needs to know this happened.
+ *
+ * The point is that a tester installs one APK and plays - no separate download,
+ * no file manager, no instructions about where to put an .obb.
+ */
+object GameDataInstaller {
+
+    private const val TAG = "GameDataInstaller"
+    private const val ASSET_NAME = "game_data.obb"
+
+    /** Progress callback: (bytes copied, total bytes). Called from a worker thread. */
+    fun interface Progress {
+        fun onProgress(copied: Long, total: Long)
+    }
+
+    sealed interface Result {
+        /** Already unpacked, or just unpacked successfully. */
+        object Ready : Result
+        /** Could not unpack - the message is safe to show a tester. */
+        data class Failed(val message: String) : Result
+    }
+
+    fun targetFile(context: Context): File {
+        val versionCode = runCatching {
+            context.packageManager.getPackageInfo(context.packageName, 0).versionCode
+        }.getOrDefault(0)
+        return File(context.obbDir, ObbHelper.getObbFileName(context, versionCode))
+    }
+
+    /** Size of the bundled asset, or -1 if it is not in this build. */
+    fun bundledSize(context: Context): Long = runCatching {
+        context.assets.openFd(ASSET_NAME).use { it.length }
+    }.getOrElse {
+        // openFd only works for an UNCOMPRESSED asset. If this ever starts
+        // failing, the noCompress rule has been lost and the asset is being
+        // deflated - worth knowing, because the copy below would still work
+        // but every install would be needlessly slower.
+        Log.w(TAG, "openFd($ASSET_NAME) failed - is noCompress still set? $it")
+        runCatching { context.assets.open(ASSET_NAME).use { s -> s.available().toLong() } }
+            .getOrDefault(-1L)
+    }
+
+    /** True when the data is already in place at its full expected size. */
+    fun isInstalled(context: Context): Boolean {
+        val expected = bundledSize(context)
+        if (expected <= 0) return false
+        val target = targetFile(context)
+        return target.isFile && target.length() == expected
+    }
+
+    /**
+     * Copies the bundled data into place. Blocking - call from a worker thread.
+     *
+     * Writes to a temporary file and renames only on success, so an interrupted
+     * copy can never leave a half-written archive that looks complete. A partial
+     * file that passed a mere "does it exist" check would send the game off to
+     * read truncated data, which fails far away from the real cause.
+     */
+    fun install(context: Context, progress: Progress?): Result {
+        val expected = bundledSize(context)
+        if (expected <= 0) {
+            return Result.Failed("В этой сборке нет игровых данных (assets/$ASSET_NAME).")
+        }
+
+        val target = targetFile(context)
+        if (target.isFile && target.length() == expected) return Result.Ready
+
+        val dir = target.parentFile
+        if (dir != null && !dir.isDirectory && !dir.mkdirs()) {
+            return Result.Failed("Не удалось создать каталог ${dir.absolutePath}")
+        }
+
+        // Check free space before starting rather than failing 500 MB in.
+        val free = dir?.freeSpace ?: 0L
+        if (free in 1 until expected) {
+            return Result.Failed(
+                "Недостаточно места: нужно ${expected / 1_048_576} МБ, свободно ${free / 1_048_576} МБ."
+            )
+        }
+
+        val tmp = File(target.parentFile, target.name + ".part")
+        tmp.delete()
+        return try {
+            var copied = 0L
+            context.assets.open(ASSET_NAME).use { input ->
+                tmp.outputStream().buffered(1 shl 20).use { output ->
+                    val buf = ByteArray(1 shl 20)
+                    while (true) {
+                        val n = input.read(buf)
+                        if (n <= 0) break
+                        output.write(buf, 0, n)
+                        copied += n
+                        progress?.onProgress(copied, expected)
+                    }
+                    output.flush()
+                }
+            }
+            if (copied != expected) {
+                tmp.delete()
+                return Result.Failed("Распаковка оборвалась: $copied из $expected байт.")
+            }
+            target.delete()
+            if (!tmp.renameTo(target)) {
+                tmp.delete()
+                return Result.Failed("Не удалось переименовать во ${target.absolutePath}")
+            }
+            Log.i(TAG, "unpacked $expected bytes to ${target.absolutePath}")
+            Result.Ready
+        } catch (e: Throwable) {
+            tmp.delete()
+            Log.w(TAG, "unpack failed", e)
+            Result.Failed("Ошибка распаковки: ${e.message}")
+        }
+    }
+}

app/src/main/java/com/ea/ironmonkey/GameDataUnpackActivity.kt

@@ -0,0 +1,148 @@
+package com.ea.ironmonkey
+
+import android.content.Intent
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.Button
+import androidx.compose.material3.LinearProgressIndicator
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Text
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableFloatStateOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import kotlin.concurrent.thread
+
+/**
+ * First-launch unpacking of the game data bundled in the APK.
+ *
+ * Shown only when [GameDataInstaller.isInstalled] is false, so it appears once
+ * after install and never again. It exists because copying ~595 MB takes long
+ * enough that a tester staring at a frozen launcher would reasonably assume the
+ * game had hung.
+ */
+class GameDataUnpackActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        enableEdgeToEdge()
+        super.onCreate(savedInstanceState)
+
+        if (GameDataInstaller.isInstalled(this)) {
+            startGame()
+            return
+        }
+
+        var fraction by mutableFloatStateOf(0f)
+        var copiedMb by mutableStateOf(0L)
+        var totalMb by mutableStateOf(0L)
+        var error by mutableStateOf<String?>(null)
+
+        setContent {
+            MaterialTheme(colorScheme = darkColorScheme()) {
+                UnpackScreen(
+                    fraction = fraction,
+                    copiedMb = copiedMb,
+                    totalMb = totalMb,
+                    error = error,
+                    onRetry = { recreate() },
+                )
+            }
+        }
+
+        thread(name = "game-data-unpack", isDaemon = true) {
+            val result = GameDataInstaller.install(this) { copied, total ->
+                // Updating Compose state is safe from any thread; the recomposition
+                // is scheduled onto the main thread by the snapshot system.
+                fraction = if (total > 0) copied.toFloat() / total else 0f
+                copiedMb = copied / 1_048_576
+                totalMb = total / 1_048_576
+            }
+            runOnUiThread {
+                when (result) {
+                    is GameDataInstaller.Result.Ready -> startGame()
+                    is GameDataInstaller.Result.Failed -> error = result.message
+                }
+            }
+        }
+    }
+
+    private fun startGame() {
+        startActivity(Intent(this, GameActivityMain::class.java))
+        finish()
+    }
+}
+
+@Composable
+private fun UnpackScreen(
+    fraction: Float,
+    copiedMb: Long,
+    totalMb: Long,
+    error: String?,
+    onRetry: () -> Unit,
+) {
+    Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .padding(innerPadding)
+                .padding(24.dp),
+            verticalArrangement = Arrangement.Center,
+            horizontalAlignment = Alignment.CenterHorizontally,
+        ) {
+            if (error != null) {
+                Text(
+                    text = "Не удалось подготовить игровые данные",
+                    style = MaterialTheme.typography.headlineSmall,
+                    textAlign = TextAlign.Center,
+                )
+                Text(
+                    text = error,
+                    style = MaterialTheme.typography.bodyMedium,
+                    textAlign = TextAlign.Center,
+                    modifier = Modifier.padding(top = 12.dp),
+                )
+                Button(onClick = onRetry, modifier = Modifier.padding(top = 24.dp)) {
+                    Text("Повторить")
+                }
+            } else {
+                Text(
+                    text = "Подготовка игровых данных",
+                    style = MaterialTheme.typography.headlineSmall,
+                    textAlign = TextAlign.Center,
+                )
+                Text(
+                    text = "Выполняется один раз после установки.",
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    textAlign = TextAlign.Center,
+                    modifier = Modifier.padding(top = 8.dp),
+                )
+                LinearProgressIndicator(
+                    progress = { fraction },
+                    modifier = Modifier
+                        .fillMaxWidth()
+                        .padding(top = 24.dp),
+                )
+                Text(
+                    text = if (totalMb > 0) "$copiedMb из $totalMb МБ" else "…",
+                    style = MaterialTheme.typography.bodySmall,
+                    modifier = Modifier.padding(top = 12.dp),
+                )
+            }
+        }
+    }
+}

app/src/main/java/com/ea/ironmonkey/GameGLSurfaceView.java

@@ -11,6 +11,10 @@ import javax.microedition.khronos.egl.EGLDisplay;
 
 public class GameGLSurfaceView extends GLSurfaceView {
     private static final String TAG = "GameGLSurfaceView";
+
+    // See createContext/destroyContext below (task #62).
+    static int eglContextCreateCount = 0;
+    static int eglContextDestroyCount = 0;
     private boolean enableHistoricalEvents;
     private boolean kMotionEvent_GetSource;
     private GameActivityMain mActivity;
@@ -35,15 +39,29 @@ public class GameGLSurfaceView extends GLSurfaceView {
         setGLESVersion2();
         setFocusable(true);
         setFocusableInTouchMode(true);
-        if (Build.VERSION.SDK_INT >= 11) {
-            try {
-                Log.i(TAG, "setPreserveEGLContextOnPause");
-                getClass().getMethod("setPreserveEGLContextOnPause", Boolean.TYPE).invoke(this, false);
-                Log.e(TAG, "setPreserveEGLContextOnPause(false) success");
-            } catch (Exception unused2) {
-                Log.e(TAG, "setPreserveEGLContextOnPause failed");
-            }
-        }
+        // Task #62 - the black-textures-after-resume bug. The shipped game asked
+        // for the context NOT to be preserved (this call passed `false`) and took
+        // responsibility for rebuilding its GL objects afterwards. Under this
+        // engine that rebuild does not happen, which was confirmed live rather
+        // than assumed:
+        //
+        //   EGL context CREATED   (#1)   launch
+        //   EGL context DESTROYED (#1)   on pause  <- every texture gone here
+        //   EGL context CREATED   (#2)   on resume
+        //
+        // and across that boundary the guest's own `Renderer::RestoreContext` ran
+        // to completion in ONE millisecond and re-uploaded a single texture, while
+        // 86 uploads had built the scene before it. Geometry survived only because
+        // vertex data is re-sent per frame; textures are uploaded once, so they
+        // came back black.
+        //
+        // Asking the platform to keep the context is the fix that does not depend
+        // on the guest restoring anything. It is a HINT, not a guarantee - the
+        // system may still drop the context under memory pressure - which is why
+        // the create/destroy logging added alongside it stays in permanently. A
+        // second CREATED line in a report means this fell back and the guest-side
+        // restore path is the next thing to fix.
+        setPreserveEGLContextOnPause(true);
     }
 
     public void setEnableHistoricalEvents(boolean z) {
@@ -56,11 +74,23 @@ public class GameGLSurfaceView extends GLSurfaceView {
 
             @Override // android.opengl.GLSurfaceView.EGLContextFactory
             public EGLContext createContext(EGL10 egl10, EGLDisplay eGLDisplay, EGLConfig eGLConfig) {
+                // Counted and logged (task #62). Whether the EGL context actually
+                // dies across a pause decides which bug we have: a SECOND create
+                // means every GL object the guest owns was destroyed and something
+                // must re-upload them, while a single create for the whole session
+                // means the black textures come from somewhere else entirely.
+                // Nothing logged this before, so the question was unanswerable.
+                eglContextCreateCount++;
+                android.util.Log.i("mpcore_log", "GameGLSurfaceView: EGL context CREATED (#"
+                        + eglContextCreateCount + ") - every GL object must be (re)uploaded after this");
                 return egl10.eglCreateContext(eGLDisplay, eGLConfig, EGL10.EGL_NO_CONTEXT, new int[]{EGL_CONTEXT_CLIENT_VERSION, 2, 12344});
             }
 
             @Override // android.opengl.GLSurfaceView.EGLContextFactory
             public void destroyContext(EGL10 egl10, EGLDisplay eGLDisplay, EGLContext eGLContext) {
+                eglContextDestroyCount++;
+                android.util.Log.i("mpcore_log", "GameGLSurfaceView: EGL context DESTROYED (#"
+                        + eglContextDestroyCount + ") - all textures, buffers and shaders are now gone");
                 egl10.eglDestroyContext(eGLDisplay, eGLContext);
             }
         });

app/src/main/java/com/ea/ironmonkey/GameRenderer.java

@@ -43,12 +43,35 @@ public class GameRenderer implements GLSurfaceView.Renderer {
         this._height = i2;
     }
 
+    // Task #47 instrumentation (2026-09-19, temporary). Settles a premise that
+    // has been reasoned from since 2026-09-18 without ever being re-verified
+    // live: that nativeOnResume runs the guest's persistent loop synchronously
+    // here and NEVER returns, so GLSurfaceView's own automatic
+    // post-onDrawFrame eglSwapBuffers stops firing. If that premise holds,
+    // this logs exactly one line reading entries=1 exits=0 and then stays
+    // silent forever. If the lines keep coming instead, onDrawFrame IS
+    // returning, the framework IS also swapping, and that is the second
+    // present of each observed pair.
+    // System.nanoTime() is CLOCK_MONOTONIC on Android - the same clock the
+    // native SWAPMARK lines use - so the two logs correlate directly.
+    private static int drawEntries = 0;
+    private static int drawExits = 0;
+    private static long lastDrawReport = 0;
+
     @Override // android.opengl.GLSurfaceView.Renderer
     public void onDrawFrame(GL10 gl10) {
+        drawEntries++;
+        long now = System.nanoTime();
+        if (now - lastDrawReport > 1000000000L) {
+            lastDrawReport = now;
+            android.util.Log.i("mpcore_log", "GameRenderer: onDrawFrame entries=" + drawEntries
+                    + " exits=" + drawExits + " t=" + now);
+        }
         if (this.drawFrameListener != null) {
             this.drawFrameListener.onDrawFrame(gl10);
         } else {
             this.activity.getRunLoop().onRunLoopTick();
         }
+        drawExits++;
     }
 }

app/src/main/java/com/ea/ironmonkey/PermissionsActivity.kt

@@ -175,7 +175,26 @@ class PermissionsActivity : AppCompatActivity() {
 
     private fun initActivity() {
         try {
-            startActivity(Intent(this, GameActivityMain::class.java))
+            // A crash report left by the previous run takes precedence over
+            // starting the game. The check lives HERE, not in GameActivityMain:
+            // this activity is the visible, foreground launcher entry, so the
+            // start is allowed. Doing it from GameActivityMain.onCreate - which
+            // starts the report and immediately finishes itself - was refused
+            // by the platform ("Activity start ONLY allowed by
+            // BAL_ALLOW_GRACE_PERIOD"), and the tester just landed back on the
+            // home screen with no report shown.
+            val next = when {
+                // A crash report from the previous run comes first - it is the
+                // thing the tester needs to see, and the next crash would
+                // overwrite it.
+                CrashReportActivity.pendingReport(this) != null -> CrashReportActivity::class.java
+                // Then the one-time unpack of the game data bundled in the APK.
+                // Checked on every launch but only does work once, so there is
+                // no cost after the first run.
+                !GameDataInstaller.isInstalled(this) -> GameDataUnpackActivity::class.java
+                else -> GameActivityMain::class.java
+            }
+            startActivity(Intent(this, next))
             finish()
         } catch (e: Exception) {
             e.printStackTrace()

app/src/main/java/nfs/mod/traceagent/TraceAgentBridge.kt

@@ -0,0 +1,12 @@
+package nfs.mod.traceagent
+
+// Bridge to the standalone libtrace_agent.so (see trace_agent/ at the repo
+// root and ARM64_TRANSLATION_LAYER.md's "Native ARM32 tracing harness"
+// plan) - diagnostic-only, for the "native32" flavor running on the Galaxy
+// A9. Not present in the APK's own jniLibs; loaded from wherever it was
+// pushed on-device (see TraceApplication).
+object TraceAgentBridge {
+    // outputPath: absolute path (app's own private files dir) the native
+    // side appends a full call trace to - see trace_agent/trace_log.h.
+    external fun install(outputPath: String)
+}

app/src/main/java/nfs/mod/traceagent/TraceApplication.kt

@@ -0,0 +1,45 @@
+package nfs.mod.traceagent
+
+import android.app.Application
+import android.content.Context
+import android.util.Log
+
+// Earliest available hook point for installing the JNI trace table patch
+// (see TraceAgentBridge/trace_agent's own comments) - as early as possible,
+// before any real game library gets a chance to grab its own JNIEnv
+// reference. Entirely inert on the normal ("translated") flavor: gated
+// behind BuildConfig.NATIVE32, and the .so path is checked for existence
+// before attempting System.load, so a normal run that never pushed
+// libtrace_agent.so to the device just logs and continues - no crash, no
+// behavior change, matching the plan's "does not touch the emulated path"
+// constraint.
+class TraceApplication : Application() {
+    override fun attachBaseContext(base: Context) {
+        super.attachBaseContext(base)
+        if (!com.ea.games.nfs13_arm.BuildConfig.NATIVE32) return
+        // Must live under the app's own private data dir (app_data_file
+        // SELinux context), not /data/local/tmp (shell_data_file) - confirmed
+        // live on the Galaxy A9 that Enforcing SELinux denies mmap-exec of a
+        // shell_data_file-labeled .so from an app-domain process ("couldn't
+        // map ... segment 1: Permission denied"). The same path is what
+        // wrap.<packageName>'s LD_PRELOAD value must point at too (see the
+        // plan's Phase 4 deployment notes).
+        val soPath = base.filesDir.absolutePath + "/libtrace_agent.so"
+        if (!java.io.File(soPath).exists()) {
+            Log.d(TAG, "libtrace_agent.so not found at $soPath - JNI tracing not installed")
+            return
+        }
+        try {
+            System.load(soPath)
+            val outputPath = base.filesDir.absolutePath + "/trace_output.log"
+            TraceAgentBridge.install(outputPath)
+            Log.d(TAG, "trace agent JNI hooks installed, writing to $outputPath")
+        } catch (e: Throwable) {
+            Log.d(TAG, "failed to install trace agent JNI hooks: $e")
+        }
+    }
+
+    companion object {
+        private const val TAG = "TraceApplication"
+    }
+}

app/src/main/jniLibs/armeabi-v7a/wrap.sh

@@ -0,0 +1,16 @@
+#!/system/bin/sh
+# APK-bundled wrap.sh (2026-09-16, ARM64_TRANSLATION_LAYER.md - trace_agent
+# LD_PRELOAD deployment investigation). The loose-file mechanism
+# (/data/local/tmp/wrap.<packageName>) was confirmed NOT invoked by zygote
+# on this specific Galaxy A9/Samsung build - a canary marker file placed by
+# that script never got created across multiple relaunches, root and
+# non-root, SELinux Enforcing and an attempted Permissive switch. This is
+# the OTHER officially documented NDK mechanism (developer.android.com/ndk/
+# guides/wrap-script): a wrap.sh bundled alongside the app's own native
+# libraries, picked up automatically for a debuggable app. Points LD_PRELOAD
+# at the app's own private files dir (not this APK-bundled location) so the
+# actual libtrace_agent.so can still be updated by just `run-as`-copying a
+# freshly-built one in, without needing to reinstall the whole APK each
+# iteration.
+export LD_PRELOAD=/data/data/com.ea.games.nfs13_arm/files/libtrace_agent.so
+exec "$@"

app/src/main/res/xml/crash_report_paths.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Shares ONLY the crash directory, nothing else. FileProvider is required
+     because targetSdk 35 rejects file:// URIs in an ACTION_SEND intent. -->
+<paths>
+    <external-files-path name="crashes" path="crashes/" />
+</paths>

app/src/test/java/com/ea/games/nfs13_arm/ExampleUnitTest.kt

@@ -1,4 +1,4 @@
-package com.ea.games.nfs13_mod
+package com.ea.games.nfs13_arm
 
 import org.junit.Test
 

docs/ARM64_TRANSLATION_LAYER.md

@@ -3635,3 +3635,59 @@ One real caveat: the flat guest mapping (task #61, the 1.24x win) exists only
 in `tcg/aarch64`. An x86_64 host silently falls back to the software MMU. That
 is recorded in a comment next to the `abiFilters` line so the next person does
 not read x86 numbers as if the same optimisation were in play.
+
+## 2026-09-22 - the first correct in-race frame rate, on two hosts
+
+Until now no in-race frame rate had ever been measured properly; the log ring
+kept wrapping before a race finished. Every speed figure in this document
+before this entry was taken somewhere else in the game. In particular the
+"51 fps" quoted for the flat-mapping A/B (task #61) was **not** measured in a
+race and must not be compared against anything below. This repeats an error
+already made once here, when a "60 fps" reading turned out to be the results
+screen.
+
+### Method
+
+`dumpsys SurfaceFlinger --latency` on the game's own BLAST layer, six
+back-to-back samples, deduplicated by actual-present timestamp, then look at
+the **distribution** of intervals rather than an average. A screenshot is
+taken with every capture - without it there is no way to know a menu was not
+measured instead of a race, which is exactly how the old numbers went wrong.
+
+### Pixel 6a, in race (60 Hz, 16.67 ms), 140 frames
+
+    median 16.72 ms (59.8 fps)   <- misleading, do not quote
+    mean   25.32 ms (39.5 fps)   <- the honest figure
+    p95    33.38 ms, worst 66.56 ms
+
+    1 vsync  (60 fps)   74 frames
+    2 vsync  (30 fps)   61 frames
+    3 vsync  (20 fps)    3 frames
+    4 vsync  (15 fps)    2 frames
+
+The distribution is bimodal. The phone very nearly makes 60 and misses on
+roughly half the frames, dropping exactly to 30. The median sat inside the
+upper lobe and reported 59.8, which is why a median is the wrong statistic
+here and the mean is quoted instead.
+
+### WayDroid x86_64, in race (144 Hz, 6.944 ms), 128 frames
+
+    median 34.72 ms (28.8 fps)
+    mean   35.05 ms (28.5 fps)
+    p95    41.68 ms, worst 48.61 ms
+
+Every frame lands on exactly five vsync periods. Slower than the phone and
+visibly smoother, because steady beats fast-but-uneven - the user described it
+as "очень плавно" before any of this was measured, and the numbers agree.
+GLThread sits at 96.7% of one core out of sixteen: CPU-bound in translation,
+not GPU-bound.
+
+### Why this changes the priorities
+
+The 6a misses the 16.67 ms budget by a few percent. So a 10-15% CPU win does
+not buy "a few more fps" - it flips those 61 two-vsync frames back to one, and
+the phone lands on a stable 60. That makes task #63 (VFP on host FP instead of
+softfloat, ~9% of profile) and task #64 (`helper_lookup_tb_ptr`, 12.18%) worth
+far more than their profile shares suggest, and it means anything new added to
+the hot path - the multiplayer hooks included - is spending a margin that is
+currently only a few percent wide.

mpcore/build.gradle.kts

@@ -11,7 +11,11 @@ android {
         minSdk = 27
 
         ndk {
-            abiFilters += listOf("armeabi-v7a")
+            // ARM64-only-device prototype (see /ARM64_TRANSLATION_LAYER.md):
+            // mpcore itself is now plain native ARM64 code that drives an
+            // embedded ARM32 CPU-emulation core (Unicorn) instead of being
+            // ARM32 code injected into a natively-loaded libapp.so.
+            abiFilters += listOf("arm64-v8a", "x86_64")
         }
 
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"

mpcore/scripts/run_heap_tests.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Desktop-only GuestHeap test harness (see guest_heap_test.cpp's own top
+# comment) - no Android, no Unicorn, no APK, no device. Compiles
+# guest_heap.cpp directly against the host's own C++ compiler and runs the
+# resulting binary. Fast feedback loop for changes to the guest heap
+# allocator before ever touching a device.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+SRC_DIR="src/main/cpp/emu"
+OUT="${TMPDIR:-/tmp}/guest_heap_test"
+
+c++ -std=c++17 -O0 -g -Wall \
+    "$SRC_DIR/guest_heap.cpp" \
+    "$SRC_DIR/tests/guest_heap_test.cpp" \
+    -I"$SRC_DIR" \
+    -o "$OUT"
+
+"$OUT"

mpcore/scripts/test_on_device.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Repeatable on-device smoke test for the ARM32-in-ARM64 prototype (see
+# /ARM64_TRANSLATION_LAYER.md). Replaces the manual adb-shell archaeology
+# this project's live debugging sessions have needed up to now: install,
+# launch, watch logcat for a bounded window, then report the same signals
+# those sessions kept hand-checking - onCreate timing, MEM FAULT count (see
+# guest_engine.cpp's mem_fault_hook_cb), and process-death cause (ANR / OOM /
+# MIUI SwipeUpClean / other) - as one command, so every future interface-
+# layer change gets checked against the same baseline instead of a fresh
+# investigation each time.
+#
+# Usage: mpcore/scripts/test_on_device.sh [device-serial] [watch-seconds]
+#   device-serial defaults to the first device `adb devices` lists.
+#   watch-seconds defaults to 180 (most observed onCreate runs finish in
+#   100-120s; this leaves headroom to also see the post-onCreate lifecycle
+#   calls that previously kept faulting).
+set -uo pipefail
+# Script lives at mpcore/scripts/ - project root (where app/ and mpcore/ are
+# siblings) is two levels up.
+cd "$(dirname "$0")/../.."
+
+PKG="com.ea.games.nfs13_arm"
+ACTIVITY="com.ea.ironmonkey.GameActivityMain"
+# "translated" (the emulated arm64-v8a path) - see app/build.gradle.kts's
+# product flavors, added for the native ARM32 tracing investigation
+# (ARM64_TRANSLATION_LAYER.md). The pre-flavor-split path
+# (app/build/outputs/apk/debug/app-debug.apk) is now a STALE, never-updated
+# file left over from before that split - silently reinstalling it here
+# instead of the real current build wasted real debugging time confirming
+# this fix, so this path is now the single source of truth.
+APK="app/build/outputs/apk/translated/debug/app-translated-debug.apk"
+
+SERIAL="${1:-$(adb devices | awk 'NR==2{print $1}')}"
+WATCH_SECONDS="${2:-180}"
+
+if [[ -z "$SERIAL" ]]; then
+    echo "No adb device found. Connect the device and retry." >&2
+    exit 1
+fi
+ADB="adb -s $SERIAL"
+
+if [[ ! -f "$APK" ]]; then
+    echo "APK not found at $APK - build it first (./gradlew :app:assembleDebug)." >&2
+    exit 1
+fi
+
+echo "== Installing $APK on $SERIAL =="
+$ADB install -r "$APK" || { echo "install failed" >&2; exit 1; }
+
+echo "== Launching =="
+$ADB shell am force-stop "$PKG"
+$ADB logcat -c
+$ADB shell monkey -p "$PKG" -c android.intent.category.LAUNCHER 1 >/dev/null
+
+sleep 2
+PID=$($ADB shell pidof "$PKG" | tr -d '\r')
+if [[ -z "$PID" ]]; then
+    echo "Process did not start." >&2
+    exit 1
+fi
+echo "pid=$PID"
+
+echo "== Watching logcat for ${WATCH_SECONDS}s =="
+LOG="$(mktemp)"
+timeout "${WATCH_SECONDS}s" $ADB logcat --pid="$PID" > "$LOG" 2>/dev/null || true
+
+echo ""
+echo "===================== RESULTS ====================="
+
+ONCREATE_LINE=$(grep "GameActivityMain onCreate took" "$LOG" | tail -1)
+if [[ -n "$ONCREATE_LINE" ]]; then
+    echo "onCreate: $(echo "$ONCREATE_LINE" | grep -oE '[0-9]+ms')"
+else
+    echo "onCreate: did not complete within ${WATCH_SECONDS}s"
+fi
+
+FAULT_COUNT=$(grep -c "MEM FAULT" "$LOG" || true)
+echo "MEM FAULT lines: $FAULT_COUNT"
+if [[ "$FAULT_COUNT" -gt 0 ]]; then
+    echo "  first: $(grep "MEM FAULT" "$LOG" | head -1)"
+    echo "  last:  $(grep "MEM FAULT" "$LOG" | tail -1)"
+fi
+
+CRASHED_LINE=$(grep -c "refusing to run - engine already crashed" "$LOG" || true)
+echo "engine crashed (fail-fast tripped): $([[ "$CRASHED_LINE" -gt 0 ]] && echo yes || echo no)"
+
+STILL_ALIVE=$($ADB shell "pidof $PKG" | tr -d '\r')
+if [[ -n "$STILL_ALIVE" ]]; then
+    echo "process status: alive (pid=$STILL_ALIVE) at end of watch window"
+else
+    echo "process status: DEAD"
+    DEATH_LINE=$($ADB logcat -d 2>/dev/null | grep -E "Killing $PID:|$PID.*died->background" | tail -3)
+    if [[ -n "$DEATH_LINE" ]]; then
+        echo "  cause:"
+        echo "$DEATH_LINE" | sed 's/^/    /'
+    else
+        echo "  cause: unknown (no ActivityManager kill/death line found - check for a FATAL crash instead)"
+        $ADB logcat -d --pid="$PID" 2>/dev/null | grep -iE "FATAL|AndroidRuntime" | sed 's/^/    /'
+    fi
+fi
+
+echo "====================================================="
+echo "Full log: $LOG"

mpcore/src/main/cpp/CMakeLists.txt

@@ -2,11 +2,71 @@ cmake_minimum_required(VERSION 3.22.1)
 
 project("mpcore")
 
+# Force an optimized build regardless of the Android Gradle Plugin's own
+# build variant (2026-09-05, "why is this ~100x slower than native"
+# investigation - see ARM64_TRANSLATION_LAYER.md). Confirmed live via the
+# actual generated build.ninja: neither this project's own C++ (guest_engine.cpp
+# et al.) nor vendored Unicorn/QEMU-TCG's own C sources ever received an -O
+# flag - AGP's external CMake integration never sets CMAKE_BUILD_TYPE here,
+# and CMake's own default (empty CMAKE_BUILD_TYPE) means no per-build-type
+# flags get added at all, i.e. plain -O0. Two separate, targeted dispatch-
+# overhead fixes made zero measurable difference to a tight guest hot loop's
+# wall-clock rate - this is why: a CPU emulator's performance is dominated
+# by how well the COMPILER optimizes its OWN interpreter/JIT dispatch, and
+# -O0 there dwarfs any micro-optimization in the C++ source. RelWithDebInfo
+# (not plain Release) keeps -g/debug info for native crash symbolication -
+# this project's own crash/fault diagnostics throughout this session depend
+# on it. FORCE + setting it before add_subdirectory so Unicorn's nested
+# CMake build (which does NOT set its own CMAKE_BUILD_TYPE) inherits it too.
+set(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "" FORCE)
+
+# ---- Vendored Unicorn Engine (ARM32-on-ARM64 CPU-emulation core) ----
+# Only the ARM (AArch32) backend is built - this project never needs any of
+# Unicorn's other target architectures. See ARM64_TRANSLATION_LAYER.md for
+# why Unicorn specifically (embeddable-by-design, MIT-licensed, QEMU-TCG-
+# derived JIT) was picked over a full QEMU-user-mode process.
+set(UNICORN_ARCH "arm" CACHE STRING "" FORCE)
+set(BUILD_SHARED_LIBS OFF CACHE BOOL "" FORCE)
+set(UNICORN_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+set(UNICORN_INSTALL OFF CACHE BOOL "" FORCE)
+set(UNICORN_FUZZ OFF CACHE BOOL "" FORCE)
+add_subdirectory(third_party/unicorn)
+
 add_library(${CMAKE_PROJECT_NAME} SHARED
         main.cpp
+        crash_handler.cpp
+        game_lifecycle_stubs.cpp
+        game_lifecycle_stubs_extra.cpp
+        game_lifecycle_stubs_extra2.cpp
         util/util.cpp
-        util/armhook.cpp)
+        util/armhook.cpp
+        emu/guest_heap.cpp
+        emu/guest_engine.cpp
+        emu/import_shims.cpp
+        emu/pthread_shim.cpp
+        emu/jni_shim.cpp
+        emu/gles_shim.cpp
+        emu/dyncast_fastpath.cpp
+        emu/libc_shims.cpp
+        emu/rtti_shims.cpp
+        emu/fmod_shims.cpp
+        emu/zlib_accel.cpp
+        emu/name_lookup_accel.cpp
+        emu/profiler.cpp
+        emu/guest_trace.cpp
+        emu/tcg_bench.cpp
+        emu/ostream_repro_test.cpp)
+
+target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE
+        third_party/unicorn/include)
+
+target_compile_features(${CMAKE_PROJECT_NAME} PRIVATE cxx_std_17)
 
 target_link_libraries(${CMAKE_PROJECT_NAME}
+        unicorn
         android
-        log)
+        log
+        GLESv2
+        z
+        EGL
+        jnigraphics)

mpcore/src/main/cpp/crash_handler.cpp

@@ -0,0 +1,283 @@
+#include "crash_handler.h"
+#include "util/util.h"
+
+#include <cerrno>
+#include <csignal>
+#include <cstring>
+#include <fcntl.h>
+#include <sys/stat.h>
+#include <sys/types.h>
+#include <sys/ucontext.h>
+#include <unistd.h>
+
+// ---- Everything below the handler boundary must be async-signal-safe ----
+//
+// The rule is narrow and unforgiving: inside the handler, only functions
+// POSIX lists as async-signal-safe may be called. write(), open(), close(),
+// _exit(), sigaction(), raise() are; snprintf(), malloc(), any C++ container,
+// anything that takes a lock, and every JNI call are NOT.
+//
+// This project already paid for ignoring that once - see
+// ARM64_TRANSLATION_LAYER.md's note that mmap() inside a SIGSEGV handler
+// deadlocked on bionic. So: every string is built HERE, at install time, and
+// the handler only appends bytes to a pre-opened path and formats integers
+// with the hand-written helpers below.
+
+namespace {
+
+constexpr size_t kPathMax = 512;
+constexpr size_t kStampMax = 256;
+
+// Pre-built at install time. `g_installed` also guards against a second
+// install and against the handler running before setup finished.
+char g_reportPath[kPathMax];
+char g_buildStamp[kStampMax];
+bool g_installed = false;
+
+// Guest memory window, for decoding a host fault address back to the guest
+// address that produced it. Plain integers written once from the engine
+// thread and only read afterwards.
+uint64_t g_guestFlatBase = 0;
+uint32_t g_guestRegionSize = 0;
+
+// The alternate stack. A stack-overflow SIGSEGV cannot be handled on the
+// stack that just overflowed, so the handler gets its own - allocated here,
+// at install time, never inside the handler.
+constexpr size_t kAltStackSize = 64 * 1024;
+char g_altStack[kAltStackSize];
+
+// Previous dispositions, so the default handler still runs afterwards and
+// Android still produces its own tombstone. Our report is extra evidence, not
+// a replacement for the system's.
+struct sigaction g_prevActions[NSIG];
+
+// ---- async-signal-safe output helpers ----
+
+void SafeWrite(int fd, const char* s, size_t len) {
+    while (len > 0) {
+        ssize_t n = write(fd, s, len);
+        if (n <= 0) {
+            if (n < 0 && errno == EINTR) continue;
+            return; // nothing useful left to do inside a handler
+        }
+        s += n;
+        len -= (size_t)n;
+    }
+}
+
+void SafeStr(int fd, const char* s) {
+    if (!s) return;
+    size_t len = 0;
+    while (s[len]) len++;
+    SafeWrite(fd, s, len);
+}
+
+void SafeHex(int fd, uint64_t v) {
+    static const char kDigits[] = "0123456789abcdef";
+    char buf[19];
+    buf[0] = '0';
+    buf[1] = 'x';
+    int pos = 18;
+    buf[pos] = '\0';
+    if (v == 0) {
+        buf[--pos] = '0';
+    } else {
+        while (v && pos > 2) {
+            buf[--pos] = kDigits[v & 0xF];
+            v >>= 4;
+        }
+    }
+    SafeWrite(fd, "0x", 2);
+    SafeStr(fd, buf + pos);
+}
+
+void SafeDec(int fd, long v) {
+    char buf[24];
+    int pos = 23;
+    buf[pos] = '\0';
+    bool neg = v < 0;
+    unsigned long u = neg ? (unsigned long)(-v) : (unsigned long)v;
+    if (u == 0) buf[--pos] = '0';
+    while (u && pos > 0) {
+        buf[--pos] = (char)('0' + (u % 10));
+        u /= 10;
+    }
+    if (neg && pos > 0) buf[--pos] = '-';
+    SafeStr(fd, buf + pos);
+}
+
+const char* SignalName(int sig) {
+    switch (sig) {
+        case SIGSEGV: return "SIGSEGV (bad memory access)";
+        case SIGBUS:  return "SIGBUS (misaligned or unmapped access)";
+        case SIGABRT: return "SIGABRT (abort - often a failed assertion or a JNI error)";
+        case SIGILL:  return "SIGILL (illegal instruction)";
+        case SIGFPE:  return "SIGFPE (arithmetic fault)";
+        default:      return "unknown signal";
+    }
+}
+
+void WriteRegisters(int fd, void* ucontextRaw) {
+    if (!ucontextRaw) return;
+    auto* uc = static_cast<ucontext_t*>(ucontextRaw);
+#if defined(__aarch64__)
+    const mcontext_t& mc = uc->uc_mcontext;
+    SafeStr(fd, "registers (host arm64):\n");
+    for (int i = 0; i < 31; i++) {
+        SafeStr(fd, "  x");
+        SafeDec(fd, i);
+        SafeStr(fd, i < 10 ? "  = " : " = ");
+        SafeHex(fd, mc.regs[i]);
+        SafeStr(fd, (i % 2) ? "\n" : "   ");
+    }
+    SafeStr(fd, "\n  sp  = ");
+    SafeHex(fd, mc.sp);
+    SafeStr(fd, "   pc  = ");
+    SafeHex(fd, mc.pc);
+    SafeStr(fd, "\n");
+
+    // x28 is where the flat guest mapping keeps its base (task #61). Printing
+    // it makes the guest-address arithmetic below checkable by hand from the
+    // report alone.
+    SafeStr(fd, "  x28 (guest base register) = ");
+    SafeHex(fd, mc.regs[28]);
+    SafeStr(fd, "\n");
+#else
+    (void)uc;
+    SafeStr(fd, "registers: not captured on this architecture\n");
+#endif
+}
+
+void CrashSignalHandler(int sig, siginfo_t* info, void* ucontextRaw) {
+    if (g_installed) {
+        // O_TRUNC, not O_APPEND: one pending report at a time. If a second
+        // crash happens before the first is collected, the newer one is the
+        // one worth having - it is the one the tester just saw.
+        int fd = open(g_reportPath, O_WRONLY | O_CREAT | O_TRUNC, 0644);
+        if (fd >= 0) {
+            SafeStr(fd, "=== NFSMW arm64 engine - native crash report ===\n\n");
+            SafeStr(fd, "build: ");
+            SafeStr(fd, g_buildStamp);
+            SafeStr(fd, "\n\nsignal: ");
+            SafeStr(fd, SignalName(sig));
+            SafeStr(fd, " (");
+            SafeDec(fd, sig);
+            SafeStr(fd, ")\n");
+
+            const uint64_t faultAddr = info ? (uint64_t)(uintptr_t)info->si_addr : 0;
+            SafeStr(fd, "fault address (host): ");
+            SafeHex(fd, faultAddr);
+            SafeStr(fd, "\n");
+
+            // The number that actually helps. A host fault address inside the
+            // guest window is really a guest pointer; reported raw it is
+            // meaningless, and nobody reading a tester's report will subtract
+            // the base by hand.
+            if (g_guestFlatBase && faultAddr >= g_guestFlatBase &&
+                faultAddr < g_guestFlatBase + 0x100000000ull) {
+                uint64_t guestAddr = faultAddr - g_guestFlatBase;
+                SafeStr(fd, "fault address (GUEST): ");
+                SafeHex(fd, guestAddr);
+                if (g_guestRegionSize && guestAddr >= g_guestRegionSize) {
+                    SafeStr(fd, "  <- BEYOND the mapped guest region (");
+                    SafeHex(fd, g_guestRegionSize);
+                    SafeStr(fd, ") - a wild pointer, not a real guest object");
+                }
+                SafeStr(fd, "\n");
+            } else if (g_guestFlatBase) {
+                SafeStr(fd, "fault address is OUTSIDE the guest window - this is a fault in the "
+                            "engine's own native code, not in emulated guest code\n");
+            }
+
+            SafeStr(fd, "thread id: ");
+            SafeDec(fd, (long)gettid());
+            SafeStr(fd, "\n\n");
+
+            WriteRegisters(fd, ucontextRaw);
+
+            SafeStr(fd,
+                    "\nnote: Android's own tombstone for this crash has more detail "
+                    "(/data/tombstones). This file exists because a tester cannot reach that.\n");
+            close(fd);
+        }
+    }
+
+    // Chain to whatever was installed before us so the platform still writes
+    // its tombstone and the process dies the way it would have. Restoring the
+    // previous action and re-raising is the portable way to do that.
+    if (sig >= 0 && sig < NSIG) {
+        sigaction(sig, &g_prevActions[sig], nullptr);
+    }
+    raise(sig);
+}
+
+} // namespace
+
+void SetCrashHandlerGuestBase(uint64_t flatBase, uint32_t regionSize) {
+    g_guestFlatBase = flatBase;
+    g_guestRegionSize = regionSize;
+}
+
+void InstallCrashHandler(const char* crashDir, const char* buildStamp) {
+    if (g_installed) return;
+    if (!crashDir || !*crashDir) {
+        Log("crash_handler: no crash directory given - native crashes will NOT be reported");
+        return;
+    }
+
+    // mkdir here, at install time. Doing it lazily from the handler would mean
+    // a filesystem call on a broken process, which is exactly what this file
+    // exists to avoid.
+    if (mkdir(crashDir, 0755) != 0 && errno != EEXIST) {
+        Log("crash_handler: could not create %s (%s) - native crashes will NOT be reported",
+            crashDir, strerror(errno));
+        return;
+    }
+
+    // Fixed filename. The handler cannot safely format a timestamp, so Java
+    // renames this to something unique when it collects it on the next launch.
+    static const char kFileName[] = "/crash_pending.txt";
+    size_t dirLen = strlen(crashDir);
+    if (dirLen + sizeof(kFileName) >= kPathMax) {
+        Log("crash_handler: crash directory path is too long (%zu) - not installing", dirLen);
+        return;
+    }
+    memcpy(g_reportPath, crashDir, dirLen);
+    memcpy(g_reportPath + dirLen, kFileName, sizeof(kFileName));
+
+    if (buildStamp) {
+        size_t n = strlen(buildStamp);
+        if (n >= kStampMax) n = kStampMax - 1;
+        memcpy(g_buildStamp, buildStamp, n);
+        g_buildStamp[n] = '\0';
+    } else {
+        memcpy(g_buildStamp, "(unknown)", sizeof("(unknown)"));
+    }
+
+    stack_t ss{};
+    ss.ss_sp = g_altStack;
+    ss.ss_size = sizeof(g_altStack);
+    ss.ss_flags = 0;
+    if (sigaltstack(&ss, nullptr) != 0) {
+        // Not fatal: without it, a stack-overflow crash goes unreported, but
+        // every other kind still works. Worth saying out loud rather than
+        // discovering the gap from a missing report later.
+        Log("crash_handler: sigaltstack failed (%s) - stack-overflow crashes will not be "
+            "reported, other crashes still will", strerror(errno));
+    }
+
+    struct sigaction sa{};
+    sa.sa_sigaction = CrashSignalHandler;
+    sa.sa_flags = SA_SIGINFO | SA_ONSTACK | SA_RESTART;
+    sigemptyset(&sa.sa_mask);
+
+    static const int kSignals[] = {SIGSEGV, SIGBUS, SIGABRT, SIGILL, SIGFPE};
+    for (int sig : kSignals) {
+        if (sigaction(sig, &sa, &g_prevActions[sig]) != 0) {
+            Log("crash_handler: could not hook signal %d (%s)", sig, strerror(errno));
+        }
+    }
+
+    g_installed = true;
+    Log("crash_handler: installed - native crashes will be written to %s", g_reportPath);
+}

mpcore/src/main/cpp/crash_handler.h

@@ -0,0 +1,33 @@
+#pragma once
+
+// Native crash reporting (task #66 / BETA_TELEMETRY_PLAN.md).
+//
+// Most crashes in this project are NATIVE - a SIGSEGV inside JIT-generated
+// code - so Java's uncaught-exception handler never sees them and the tester
+// sees only "the game closed". This writes a report the moment it happens.
+//
+// What it does NOT do, deliberately: show any UI. A signal handler runs on a
+// process that has already gone wrong, where only async-signal-safe calls are
+// legal - no malloc, no JNI, no Activity. It writes one file with write() and
+// then lets the process die. The report screen is shown by Java on the NEXT
+// launch, which is how every serious crash reporter handles native crashes.
+//
+// The report lands on external storage (Android/data/<pkg>/files/crashes), so
+// a tester can reach it over USB or a file manager without any permission.
+
+#include <cstdint>
+
+// Call once, early, with the directory reports should be written to (the app's
+// external files dir). Creates the directory if needed, pre-builds every string
+// the handler will need, installs an alternate signal stack so a stack-overflow
+// crash can still be reported, and hooks the fatal signals.
+//
+// Safe to call more than once; only the first call installs anything.
+void InstallCrashHandler(const char* crashDir, const char* buildStamp);
+
+// Tells the handler where guest memory starts, so a host fault address can be
+// reported as the GUEST address that caused it. Without this a report says
+// "fault at 0x6f464c459b", which means nothing to anyone; with it the report
+// also says "guest 0x464c459b", which is the number worth reading. Called by
+// GuestEngine once its region is mapped.
+void SetCrashHandlerGuestBase(uint64_t flatBase, uint32_t regionSize);

mpcore/src/main/cpp/emu/dyncast_fastpath.cpp

@@ -0,0 +1,131 @@
+// Guest-side __dynamic_cast fast path (task #59, 2026-09-19).
+//
+// WHY THIS EXISTS, and why it inverts this project's usual instinct.
+//
+// Everything accelerated so far - crc32, inflate, the FNV hash - was moved
+// TO THE HOST, because host code is faster than emulated code. __dynamic_cast
+// is the opposite case, and the measurements say so plainly:
+//
+//   - It is 49% of ALL shim crossings during a prologue load (284,986/sec),
+//     found by the per-shim TOPSHIMS counter.
+//   - Native ARM32 on the A9 calls it up to 824,200/sec - roughly THREE TIMES
+//     more (trace_agent's DYNCAST interposer, task #58). So our rate is not
+//     what the guest wants, it is all we can supply: the boundary is
+//     throttling it.
+//   - Cheapening the boundary generally (lock-free dispatch, batched register
+//     reads - commit 9c4a455) bought only ~3%.
+//
+// So the win is not in making the call faster, it is in NOT CROSSING. The
+// algorithm reads only guest memory (an object's vtable, vtable[-1] = dynamic
+// type, vtable[-2] = offset-to-top) and needs nothing from the host, so it can
+// run as ordinary emulated ARM32 with zero crossings. Emulated-but-not-
+// crossing beats native-but-crossing here.
+//
+// HOW SMALL IT CAN BE, measured rather than assumed. Instrumenting
+// Shim_dynamic_cast over one prologue load (2,745,185 calls):
+//
+//     exact match at depth 0 ... 84.2%   <- dynamic type already IS the target
+//     one base (depth 1) ....... 0.4%
+//     deeper ................... 0.0%    (max depth all run: 3)
+//     not found ................ 15.4%
+//
+// 84% need no hierarchy walk at all. This handles exactly that case and tail-
+// calls the existing host shim for everything else, so correctness is
+// unchanged - the fallback is the same code that served every call before.
+// Removing 84% of a 49% share removes ~41% of the total crossing load.
+
+#include "dyncast_fastpath.h"
+#include "guest_engine.h"
+#include "../util/util.h"
+#include <cstring>
+
+namespace {
+
+// Assembled with the NDK's clang for armv7a Thumb-2 (not hand-encoded - see
+// this file's .S source kept below verbatim, and objdump output that was
+// checked against it). Clobbers ONLY r12, deliberately: r1 (src type_info)
+// and r3 (src2dst hint) must reach the fallback untouched, which is why the
+// hit path re-loads the vtable instead of keeping it in a second register.
+//
+//   dyncast_fast:                       @ r0=sub r1=src r2=dst r3=hint
+//       cmp     r0, #0
+//       beq     .Lret0
+//       ldr     r12, [r0]               @ vtable pointer
+//       cmp     r12, #0
+//       beq     .Lret0
+//       ldr     r12, [r12, #-4]         @ vtable[-1] = dynamic type_info
+//       cmp     r12, r2
+//       bne     .Lslow                  @ not an exact match -> host shim
+//       ldr     r12, [r0]
+//       ldr     r12, [r12, #-8]         @ vtable[-2] = offset-to-top
+//       add     r0, r0, r12
+//       bx      lr
+//   .Lret0:
+//       movs    r0, #0
+//       bx      lr
+//   .Lslow:
+//       ldr     r12, .Lslowaddr
+//       bx      r12
+//       .align  2
+//   .Lslowaddr:
+//       .word   0xDEADBEEF              @ patched with the slow-path stub
+const uint8_t kFastPathCode[] = {
+    0x00, 0x28, 0x0e, 0xd0, 0xd0, 0xf8, 0x00, 0xc0,
+    0xbc, 0xf1, 0x00, 0x0f, 0x09, 0xd0, 0x5c, 0xf8,
+    0x04, 0xcc, 0x94, 0x45, 0x07, 0xd1, 0xd0, 0xf8,
+    0x00, 0xc0, 0x5c, 0xf8, 0x08, 0xcc, 0x60, 0x44,
+    0x70, 0x47, 0x00, 0x20, 0x70, 0x47, 0xdf, 0xf8,
+    0x04, 0xc0, 0x60, 0x47, 0xef, 0xbe, 0xad, 0xde,
+};
+constexpr uint32_t kSlowAddrPatchOffset = 44; // the 0xDEADBEEF word
+
+} // namespace
+
+// A/B switch (temporary): false leaves __dynamic_cast entirely on the host
+// shim, so the control-arena permission change can be measured WITHOUT the
+// fast path confounding it - the two landed together and must be separated
+// before either is judged.
+static constexpr bool kEnableGuestFastPath = false;
+
+void RegisterDynamicCastFastPath(GuestEngine& engine) {
+    if (!kEnableGuestFastPath) {
+        Log("dyncast_fastpath: guest fast path DISABLED (kEnableGuestFastPath=false) - "
+            "__dynamic_cast stays on the host shim");
+        return;
+    }
+    engine.RegisterDataSymbolSetup([](GuestEngine& eng) {
+        // The fallback target. Registered under its own name so that
+        // ResolveOrCreateImportStub still builds a real callable stub for it -
+        // the data symbol installed below would otherwise win for the name
+        // "__dynamic_cast" and no stub would ever exist to fall back to.
+        GuestAddr slowStub = eng.ResolveOrCreateImportStub("__dynamic_cast_slowpath");
+        if (!slowStub) {
+            Log("dyncast_fastpath: could not create the slow-path stub - leaving __dynamic_cast "
+                "on the host shim entirely (no fast path installed)");
+            return;
+        }
+
+        // AllocGuestCode, NOT AllocPermanent: the latter carves from the
+        // control arena, which is mapped read-write only. Placing code there
+        // produced an immediate FETCH_PROT at this function's own entry, and
+        // making that arena executable to accommodate it cost a measured ~4s
+        // of load time (more than this fast path saves). The trampoline arena
+        // is already executable and is not a write-hot region.
+        GuestAddr code = eng.AllocGuestCode(sizeof(kFastPathCode));
+        if (!code) {
+            Log("dyncast_fastpath: AllocGuestCode(%zu) failed - leaving __dynamic_cast on the "
+                "host shim entirely (no fast path installed)", sizeof(kFastPathCode));
+            return;
+        }
+        memcpy(eng.G2H(code), kFastPathCode, sizeof(kFastPathCode));
+        memcpy(eng.G2H(code + kSlowAddrPatchOffset), &slowStub, 4);
+
+        // Thumb bit - this engine's only real mode (see MapSegments). Without
+        // it the guest would branch here in ARM mode and misdecode every byte.
+        GuestAddr entry = code | 1u;
+        eng.RegisterDataSymbol("__dynamic_cast", entry);
+        Log("dyncast_fastpath: __dynamic_cast now resolves to guest code at 0x%x (slow path stub "
+            "0x%x) - the 84%% exact-match case no longer crosses the shim boundary",
+            entry, slowStub);
+    });
+}

mpcore/src/main/cpp/emu/dyncast_fastpath.h

@@ -0,0 +1,13 @@
+#pragma once
+
+// Installs a guest-side ARM32 fast path for __dynamic_cast so the common case
+// never crosses the shim boundary. See dyncast_fastpath.cpp's own comment for
+// the measurements that motivated it (it is 49% of all crossings, native calls
+// it 3x more often than we can serve, and 84% of calls need no hierarchy walk).
+//
+// Must be called during shim registration, BEFORE the image is loaded: it
+// registers a data-symbol setup function, which the loader runs after
+// MapSegments (AllocPermanent is live by then) and before ProcessRelocations
+// (so the resolved address reaches the GOT).
+class GuestEngine;
+void RegisterDynamicCastFastPath(GuestEngine& engine);

mpcore/src/main/cpp/emu/fmod_shims.cpp

@@ -0,0 +1,403 @@
+#include "fmod_shims.h"
+#include <cstring>
+#include <mutex>
+#include <set>
+
+namespace {
+
+constexpr uint32_t kFmodOk = 0;
+
+// 2026-09-06 (ARM64_TRANSLATION_LAYER.md "PC wanders into .data/.bss"
+// investigation): FakeHandle used to hand out 16 raw AllocPermanent bytes
+// with NO vtable pointer set (i.e. a real 0 at offset 0). That's fine for
+// the handful of calls this file itself makes on a fake object (none - it
+// never dereferences its own handles), but real guest code that later
+// calls a genuinely virtual method through one of these handles (confirmed
+// live: SoundManager::SetVolume calling EventCategory::setVolume via
+// vtable+0x20 on a getCategory() fake handle) reads *(0+0x20) - the guest's
+// own ELF header's e_shoff field, a real but unrelated large integer - and
+// jumps into it as code, landing deep in .data with no diagnostic trail
+// pointing back here. Give every fake handle a real, generous, callable
+// vtable whose slots all just return 0/kFmodOk instead - same pattern this
+// project already uses for RTTI/libc++ facet objects it doesn't fully
+// reimplement (see rtti_shims.cpp's ctype<char>/num_put<char> vtables).
+// Built once, shared by every FakeHandle() call (all real FMOD interfaces
+// this project stubs - EventSystem, Event, EventCategory, ChannelGroup,
+// DSP, Sound, Channel - are small enough that no real vtable comes close
+// to 64 slots).
+GuestAddr g_fmodNoOpVtable = 0;
+GuestAddr FmodNoOpVtable(GuestEngine& eng) {
+    if (g_fmodNoOpVtable) return g_fmodNoOpVtable;
+    constexpr int kSlots = 64;
+    GuestAddr vtable = eng.AllocPermanent((uint32_t)kSlots * 4);
+    for (int i = 0; i < kSlots; i++) {
+        GuestAddr stub = eng.AllocCodeStub(
+            [](uc_engine* uc, uint64_t, uint32_t, void*) {
+                uint32_t zero = 0;
+                uc_reg_write(uc, UC_ARM_REG_R0, &zero);
+            },
+            nullptr);
+        if (vtable && stub) memcpy(eng.G2H(vtable + (uint32_t)i * 4), &stub, 4);
+    }
+    g_fmodNoOpVtable = vtable;
+    return vtable;
+}
+// FIX (2026-09-19): this used to call AllocPermanent(16) on EVERY invocation.
+// AllocPermanent is a bump allocator that never frees (by design - see its
+// own comment), while FakeHandle is called from every FMOD factory/getter
+// shim below (EventSystem_Create, getEvent, getChannel, getSound, ...), which
+// the game hits continuously while loading a level. That is an unbounded
+// leak: confirmed live on the Pixel 6a, where a prologue load drained the
+// control arena and then logged "control arena exhausted (requested 16 bytes,
+// 0 remaining)" roughly 120 times a second, indefinitely. Raising the arena
+// size did not help and could not have - a leak is not a capacity problem.
+//
+// These handles are interchangeable opaque dummies: their only content is the
+// shared no-op vtable pointer, and every shim that receives one ignores it
+// and returns kFmodOk. So they are recycled from a fixed pool allocated once.
+// The pool keeps them DISTINCT rather than returning one singleton, because
+// guest code may legitimately compare two handles for inequality (e.g. "find
+// a channel that isn't the current one"), and a single shared address could
+// turn such a search into a spin. 1024 far exceeds the number of FMOD objects
+// the game holds live at once, so live handles never alias in practice.
+constexpr int kFakeHandlePoolSize = 1024;
+GuestAddr g_fakeHandlePool = 0;
+int g_fakeHandleCursor = 0;
+
+GuestAddr FakeHandle(GuestEngine& eng) {
+    GuestAddr vt = FmodNoOpVtable(eng);
+    if (!g_fakeHandlePool) {
+        g_fakeHandlePool = eng.AllocPermanent(kFakeHandlePoolSize * 16);
+        if (!g_fakeHandlePool) return 0;
+        // Every slot carries the same vtable pointer; the remaining 12 bytes
+        // stay zero, exactly as the per-call version left them.
+        for (int i = 0; i < kFakeHandlePoolSize; i++) {
+            GuestAddr slot = g_fakeHandlePool + (uint32_t)i * 16;
+            if (vt) memcpy(eng.G2H(slot), &vt, 4);
+        }
+    }
+    GuestAddr obj = g_fakeHandlePool + (uint32_t)g_fakeHandleCursor * 16;
+    g_fakeHandleCursor = (g_fakeHandleCursor + 1) % kFakeHandlePoolSize;
+    return obj;
+}
+void OutPtr(GuestEngine& eng, uint32_t slot, GuestAddr v) { if (slot) memcpy(eng.G2H(slot), &v, 4); }
+void OutFloat(GuestEngine& eng, uint32_t slot, float v) { if (slot) memcpy(eng.G2H(slot), &v, 4); }
+void OutBool(GuestEngine& eng, uint32_t slot, bool v) { if (slot) { uint32_t b = v ? 1u : 0u; memcpy(eng.G2H(slot), &b, 4); } }
+void OutU32(GuestEngine& eng, uint32_t slot, uint32_t v) { if (slot) memcpy(eng.G2H(slot), &v, 4); }
+// FMOD_VECTOR = 3 floats (12 bytes) - stable/unchanged across every FMOD
+// version, safe to zero exactly (unlike the bigger, uncertain structs this
+// file otherwise leaves untouched - see fmod_shims.h's own comment).
+void OutVectorZero(GuestEngine& eng, uint32_t slot) { if (slot) memset(eng.G2H(slot), 0, 12); }
+
+// ---- Factory functions ----
+uint32_t Shim_FMOD_EventSystem_Create(GuestEngine& eng, uint32_t out, uint32_t, uint32_t, uint32_t, uint32_t) {
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+uint32_t Shim_FMOD_Memory_Initialize(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+
+// ---- EventSystem ----
+uint32_t Shim_EventSystem_init(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_EventSystem_update(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_EventSystem_release(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_EventSystem_getSystemObject(GuestEngine& eng, uint32_t, uint32_t out, uint32_t, uint32_t, uint32_t) {
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+uint32_t Shim_EventSystem_getMusicSystem(GuestEngine& eng, uint32_t, uint32_t out, uint32_t, uint32_t, uint32_t) {
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+uint32_t Shim_EventSystem_getEvent(GuestEngine& eng, uint32_t, uint32_t, uint32_t, uint32_t out, uint32_t) {
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+uint32_t Shim_EventSystem_getGroup(GuestEngine& eng, uint32_t, uint32_t, uint32_t, uint32_t out, uint32_t) {
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+uint32_t Shim_EventSystem_getCategory(GuestEngine& eng, uint32_t, uint32_t, uint32_t out, uint32_t, uint32_t) {
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+uint32_t Shim_EventSystem_load(GuestEngine& eng, uint32_t, uint32_t, uint32_t, uint32_t out, uint32_t) {
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+uint32_t Shim_EventSystem_getReverbPreset(GuestEngine& eng, uint32_t, uint32_t, uint32_t, uint32_t indexOut, uint32_t) {
+    OutU32(eng, indexOut, 0);
+    return kFmodOk; // FMOD_REVERB_PROPERTIES* left untouched - size not independently confirmed, see fmod_shims.h
+}
+uint32_t Shim_EventSystem_setReverbProperties(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_EventSystem_set3DListenerAttributes(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+
+// ---- ChannelGroup ----
+uint32_t Shim_ChannelGroup_getSystemObject(GuestEngine& eng, uint32_t, uint32_t out, uint32_t, uint32_t, uint32_t) {
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+uint32_t Shim_ChannelGroup_addDSP(GuestEngine& eng, uint32_t, uint32_t, uint32_t out, uint32_t, uint32_t) {
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+
+// ---- EventParameter ----
+uint32_t Shim_EventParameter_keyOff(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_EventParameter_getValue(GuestEngine& eng, uint32_t, uint32_t out, uint32_t, uint32_t, uint32_t) {
+    OutFloat(eng, out, 0.0f);
+    return kFmodOk;
+}
+uint32_t Shim_EventParameter_setValue(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+
+// ---- DSP ----
+uint32_t Shim_DSP_setParameter(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_DSP_release(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+
+// ---- Event ----
+uint32_t Shim_Event_getCategory(GuestEngine& eng, uint32_t, uint32_t out, uint32_t, uint32_t, uint32_t) {
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+uint32_t Shim_Event_setCallback(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; } // callback never invoked - no real event ever fires
+uint32_t Shim_Event_getParameter(GuestEngine& eng, uint32_t, uint32_t, uint32_t out, uint32_t, uint32_t) {
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+uint32_t Shim_Event_get3DOcclusion(GuestEngine& eng, uint32_t, uint32_t out1, uint32_t out2, uint32_t, uint32_t) {
+    OutFloat(eng, out1, 0.0f);
+    OutFloat(eng, out2, 0.0f);
+    return kFmodOk;
+}
+uint32_t Shim_Event_set3DOcclusion(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_Event_get3DAttributes(GuestEngine& eng, uint32_t, uint32_t out1, uint32_t out2, uint32_t, uint32_t) {
+    OutVectorZero(eng, out1);
+    OutVectorZero(eng, out2);
+    return kFmodOk;
+}
+uint32_t Shim_Event_getChannelGroup(GuestEngine& eng, uint32_t, uint32_t out, uint32_t, uint32_t, uint32_t) {
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+uint32_t Shim_Event_set3DAttributes(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_Event_setPropertyByIndex(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_Event_stop(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_Event_start(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_Event_getInfo(GuestEngine& eng, uint32_t, uint32_t indexOut, uint32_t, uint32_t, uint32_t) {
+    OutU32(eng, indexOut, 0);
+    return kFmodOk; // name (char**) and FMOD_EVENT_INFO* left untouched - see fmod_shims.h
+}
+uint32_t Shim_Event_getMute(GuestEngine& eng, uint32_t, uint32_t out, uint32_t, uint32_t, uint32_t) {
+    OutBool(eng, out, false);
+    return kFmodOk;
+}
+uint32_t Shim_Event_release(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_Event_setMute(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_Event_getPitch(GuestEngine& eng, uint32_t, uint32_t out, uint32_t, uint32_t, uint32_t) {
+    OutFloat(eng, out, 1.0f); // neutral pitch
+    return kFmodOk;
+}
+uint32_t Shim_Event_getState(GuestEngine& eng, uint32_t, uint32_t out, uint32_t, uint32_t, uint32_t) {
+    OutU32(eng, out, 0); // no state flags active - not playing/loading/etc
+    return kFmodOk;
+}
+uint32_t Shim_Event_setPitch(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_Event_getPaused(GuestEngine& eng, uint32_t, uint32_t out, uint32_t, uint32_t, uint32_t) {
+    OutBool(eng, out, false);
+    return kFmodOk;
+}
+uint32_t Shim_Event_getVolume(GuestEngine& eng, uint32_t, uint32_t out, uint32_t, uint32_t, uint32_t) {
+    OutFloat(eng, out, 1.0f);
+    return kFmodOk;
+}
+uint32_t Shim_Event_setPaused(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_Event_setVolume(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+
+// ---- Sound ----
+uint32_t Shim_Sound_release(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+
+// ---- System ----
+uint32_t Shim_System_createSound(GuestEngine& eng, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t sp) {
+    uint32_t out = eng.ReadIncomingArg(4, 0, 0, 0, 0, sp); // 5th total arg (this,name,mode,exinfo,+sound**)
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+uint32_t Shim_System_getCPUUsage(GuestEngine& eng, uint32_t, uint32_t out1, uint32_t out2, uint32_t out3, uint32_t sp) {
+    uint32_t out4 = eng.ReadIncomingArg(4, 0, out1, out2, out3, sp);
+    uint32_t out5 = eng.ReadIncomingArg(5, 0, out1, out2, out3, sp);
+    OutFloat(eng, out1, 0.0f);
+    OutFloat(eng, out2, 0.0f);
+    OutFloat(eng, out3, 0.0f);
+    OutFloat(eng, out4, 0.0f);
+    OutFloat(eng, out5, 0.0f);
+    return kFmodOk;
+}
+uint32_t Shim_System_setFileSystem(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) {
+    // Real signature takes ~10 args (mostly guest function-pointer
+    // callbacks for async file I/O) - none of them will ever be called
+    // (no real audio, no real file streaming), so there's nothing worth
+    // reading even the extra stack args for.
+    return kFmodOk;
+}
+uint32_t Shim_System_setSpeakerMode(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_System_createDSPByType(GuestEngine& eng, uint32_t, uint32_t, uint32_t out, uint32_t, uint32_t) {
+    OutPtr(eng, out, FakeHandle(eng));
+    return kFmodOk;
+}
+uint32_t Shim_System_setDSPBufferSize(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_System_getSoftwareFormat(GuestEngine& eng, uint32_t, uint32_t out1, uint32_t out2, uint32_t out3, uint32_t sp) {
+    uint32_t out4 = eng.ReadIncomingArg(4, 0, out1, out2, out3, sp);
+    uint32_t out5 = eng.ReadIncomingArg(5, 0, out1, out2, out3, sp);
+    uint32_t out6 = eng.ReadIncomingArg(6, 0, out1, out2, out3, sp);
+    OutU32(eng, out1, 0);
+    OutU32(eng, out2, 0);
+    OutU32(eng, out3, 0);
+    OutU32(eng, out4, 0);
+    OutU32(eng, out5, 0);
+    OutU32(eng, out6, 0);
+    return kFmodOk;
+}
+uint32_t Shim_System_setSoftwareFormat(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_System_set3DSpeakerPosition(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+// FIX (2026-09-19, task #49). Channels handed out by System::playSound and
+// not yet stopped. Without this the music never played: playSound reported
+// success and returned a fake channel, then Channel::isPlaying answered
+// FALSE for it, so the game concluded the track had finished and immediately
+// started the next one - forever. Measured in the pause menu: a different
+// track roughly every 1.5s, picked non-sequentially (DEAD SARA, DEAD SARA,
+// GREEN DAY, SKRILLEX, GREEN DAY, CROSSES, ICONA POP, JOY FORMIDABLE), so
+// not a walk through playlists.sb but a fresh selection each time.
+//
+// Third instance today of the same failure shape - a shim reporting SUCCESS
+// while handing back an empty/negative value (see AndroidBitmap_lockPixels
+// in gles_shim.cpp, task #41). Hence the log below: this engine has no audio
+// backend, so playback here is simulated, and that fact belongs in the log
+// rather than only in a comment.
+std::set<uint32_t> g_playingChannels;
+std::mutex g_playingChannelsMutex;
+
+uint32_t Shim_System_playSound(GuestEngine& eng, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t sp) {
+    uint32_t out = eng.ReadIncomingArg(4, 0, 0, 0, 0, sp); // 5th total arg (this,channelid,sound,paused,+channel**)
+    GuestAddr channel = FakeHandle(eng);
+    OutPtr(eng, out, channel);
+    {
+        std::lock_guard<std::mutex> lock(g_playingChannelsMutex);
+        g_playingChannels.insert(channel);
+    }
+    static std::once_flag once;
+    std::call_once(once, [] {
+        Log("fmod_shims: no audio backend - System::playSound will report channels as PLAYING until "
+            "the guest stops them. Sound is silent by design; without this the guest sees every track "
+            "finish instantly and thrashes through the playlist (task #49).");
+    });
+    return kFmodOk;
+}
+uint32_t Shim_System_setOutput(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+
+// ---- Channel ----
+uint32_t Shim_Channel_setCallback(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_Channel_setPriority(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_Channel_stop(GuestEngine&, uint32_t r0, uint32_t, uint32_t, uint32_t, uint32_t) {
+    // r0 is `this`. Dropping it here is what lets the guest end a track on its
+    // own terms - the next isPlaying() then honestly answers false, so normal
+    // transitions (race ends, menu change) still work.
+    std::lock_guard<std::mutex> lock(g_playingChannelsMutex);
+    g_playingChannels.erase(r0);
+    return kFmodOk;
+}
+uint32_t Shim_Channel_setMute(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_Channel_getPaused(GuestEngine& eng, uint32_t, uint32_t out, uint32_t, uint32_t, uint32_t) {
+    OutBool(eng, out, false);
+    return kFmodOk;
+}
+uint32_t Shim_Channel_isPlaying(GuestEngine& eng, uint32_t r0, uint32_t out, uint32_t, uint32_t, uint32_t) {
+    // See g_playingChannels' comment. Answering "playing" only for channels we
+    // actually handed out - rather than a blanket true - keeps a stale or
+    // never-started channel honest.
+    bool playing;
+    {
+        std::lock_guard<std::mutex> lock(g_playingChannelsMutex);
+        playing = g_playingChannels.count(r0) != 0;
+    }
+    OutBool(eng, out, playing);
+    return kFmodOk;
+}
+uint32_t Shim_Channel_setPaused(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+uint32_t Shim_Channel_setVolume(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return kFmodOk; }
+
+} // namespace
+
+void RegisterFmodImportShims(GuestEngine& engine) {
+    engine.RegisterImportShim("FMOD_EventSystem_Create", Shim_FMOD_EventSystem_Create);
+    engine.RegisterImportShim("FMOD_Memory_Initialize", Shim_FMOD_Memory_Initialize);
+
+    engine.RegisterImportShim("_ZN4FMOD11EventSystem4initEijPvj", Shim_EventSystem_init);
+    engine.RegisterImportShim("_ZN4FMOD11EventSystem6updateEv", Shim_EventSystem_update);
+    engine.RegisterImportShim("_ZN4FMOD11EventSystem7releaseEv", Shim_EventSystem_release);
+    engine.RegisterImportShim("_ZN4FMOD11EventSystem15getSystemObjectEPPNS_6SystemE", Shim_EventSystem_getSystemObject);
+    engine.RegisterImportShim("_ZN4FMOD11EventSystem14getMusicSystemEPPNS_11MusicSystemE", Shim_EventSystem_getMusicSystem);
+    engine.RegisterImportShim("_ZN4FMOD11EventSystem8getEventEPKcjPPNS_5EventE", Shim_EventSystem_getEvent);
+    engine.RegisterImportShim("_ZN4FMOD11EventSystem8getGroupEPKcbPPNS_10EventGroupE", Shim_EventSystem_getGroup);
+    engine.RegisterImportShim("_ZN4FMOD11EventSystem11getCategoryEPKcPPNS_13EventCategoryE", Shim_EventSystem_getCategory);
+    engine.RegisterImportShim("_ZN4FMOD11EventSystem4loadEPKcP19FMOD_EVENT_LOADINFOPPNS_12EventProjectE", Shim_EventSystem_load);
+    engine.RegisterImportShim("_ZN4FMOD11EventSystem15getReverbPresetEPKcP22FMOD_REVERB_PROPERTIESPi", Shim_EventSystem_getReverbPreset);
+    engine.RegisterImportShim("_ZN4FMOD11EventSystem19setReverbPropertiesEPK22FMOD_REVERB_PROPERTIES", Shim_EventSystem_setReverbProperties);
+    engine.RegisterImportShim("_ZN4FMOD11EventSystem23set3DListenerAttributesEiPK11FMOD_VECTORS3_S3_S3_", Shim_EventSystem_set3DListenerAttributes);
+
+    engine.RegisterImportShim("_ZN4FMOD12ChannelGroup15getSystemObjectEPPNS_6SystemE", Shim_ChannelGroup_getSystemObject);
+    engine.RegisterImportShim("_ZN4FMOD12ChannelGroup6addDSPEPNS_3DSPEPPNS_13DSPConnectionE", Shim_ChannelGroup_addDSP);
+
+    engine.RegisterImportShim("_ZN4FMOD14EventParameter6keyOffEv", Shim_EventParameter_keyOff);
+    engine.RegisterImportShim("_ZN4FMOD14EventParameter8getValueEPf", Shim_EventParameter_getValue);
+    engine.RegisterImportShim("_ZN4FMOD14EventParameter8setValueEf", Shim_EventParameter_setValue);
+
+    engine.RegisterImportShim("_ZN4FMOD3DSP12setParameterEif", Shim_DSP_setParameter);
+    engine.RegisterImportShim("_ZN4FMOD3DSP7releaseEv", Shim_DSP_release);
+
+    engine.RegisterImportShim("_ZN4FMOD5Event11getCategoryEPPNS_13EventCategoryE", Shim_Event_getCategory);
+    engine.RegisterImportShim("_ZN4FMOD5Event11setCallbackEPF11FMOD_RESULTP10FMOD_EVENT23FMOD_EVENT_CALLBACKTYPEPvS5_S5_ES5_", Shim_Event_setCallback);
+    engine.RegisterImportShim("_ZN4FMOD5Event12getParameterEPKcPPNS_14EventParameterE", Shim_Event_getParameter);
+    engine.RegisterImportShim("_ZN4FMOD5Event14get3DOcclusionEPfS1_", Shim_Event_get3DOcclusion);
+    engine.RegisterImportShim("_ZN4FMOD5Event14set3DOcclusionEff", Shim_Event_set3DOcclusion);
+    engine.RegisterImportShim("_ZN4FMOD5Event15get3DAttributesEP11FMOD_VECTORS2_S2_", Shim_Event_get3DAttributes);
+    engine.RegisterImportShim("_ZN4FMOD5Event15getChannelGroupEPPNS_12ChannelGroupE", Shim_Event_getChannelGroup);
+    engine.RegisterImportShim("_ZN4FMOD5Event15set3DAttributesEPK11FMOD_VECTORS3_S3_", Shim_Event_set3DAttributes);
+    engine.RegisterImportShim("_ZN4FMOD5Event18setPropertyByIndexEiPvb", Shim_Event_setPropertyByIndex);
+    engine.RegisterImportShim("_ZN4FMOD5Event4stopEb", Shim_Event_stop);
+    engine.RegisterImportShim("_ZN4FMOD5Event5startEv", Shim_Event_start);
+    engine.RegisterImportShim("_ZN4FMOD5Event7getInfoEPiPPcP15FMOD_EVENT_INFO", Shim_Event_getInfo);
+    engine.RegisterImportShim("_ZN4FMOD5Event7getMuteEPb", Shim_Event_getMute);
+    engine.RegisterImportShim("_ZN4FMOD5Event7releaseEbb", Shim_Event_release);
+    engine.RegisterImportShim("_ZN4FMOD5Event7setMuteEb", Shim_Event_setMute);
+    engine.RegisterImportShim("_ZN4FMOD5Event8getPitchEPf21FMOD_EVENT_PITCHUNITS", Shim_Event_getPitch);
+    engine.RegisterImportShim("_ZN4FMOD5Event8getStateEPj", Shim_Event_getState);
+    engine.RegisterImportShim("_ZN4FMOD5Event8setPitchEf21FMOD_EVENT_PITCHUNITS", Shim_Event_setPitch);
+    engine.RegisterImportShim("_ZN4FMOD5Event9getPausedEPb", Shim_Event_getPaused);
+    engine.RegisterImportShim("_ZN4FMOD5Event9getVolumeEPf", Shim_Event_getVolume);
+    engine.RegisterImportShim("_ZN4FMOD5Event9setPausedEb", Shim_Event_setPaused);
+    engine.RegisterImportShim("_ZN4FMOD5Event9setVolumeEf", Shim_Event_setVolume);
+
+    engine.RegisterImportShim("_ZN4FMOD5Sound7releaseEv", Shim_Sound_release);
+
+    engine.RegisterImportShim("_ZN4FMOD6System11createSoundEPKcjP22FMOD_CREATESOUNDEXINFOPPNS_5SoundE", Shim_System_createSound);
+    engine.RegisterImportShim("_ZN4FMOD6System11getCPUUsageEPfS1_S1_S1_S1_", Shim_System_getCPUUsage);
+    engine.RegisterImportShim(
+        "_ZN4FMOD6System13setFileSystemEPF11FMOD_RESULTPKciPjPPvS6_EPFS1_S5_S5_EPFS1_S5_S5_jS4_S5_EPFS1_S5_jS5_EPFS1_P18FMOD_ASYNCREADINFOS5_ESA_i",
+        Shim_System_setFileSystem);
+    engine.RegisterImportShim("_ZN4FMOD6System14setSpeakerModeE16FMOD_SPEAKERMODE", Shim_System_setSpeakerMode);
+    engine.RegisterImportShim("_ZN4FMOD6System15createDSPByTypeE13FMOD_DSP_TYPEPPNS_3DSPE", Shim_System_createDSPByType);
+    engine.RegisterImportShim("_ZN4FMOD6System16setDSPBufferSizeEji", Shim_System_setDSPBufferSize);
+    engine.RegisterImportShim("_ZN4FMOD6System17getSoftwareFormatEPiP17FMOD_SOUND_FORMATS1_S1_P18FMOD_DSP_RESAMPLERS1_", Shim_System_getSoftwareFormat);
+    engine.RegisterImportShim("_ZN4FMOD6System17setSoftwareFormatEi17FMOD_SOUND_FORMATii18FMOD_DSP_RESAMPLER", Shim_System_setSoftwareFormat);
+    engine.RegisterImportShim("_ZN4FMOD6System20set3DSpeakerPositionE12FMOD_SPEAKERffb", Shim_System_set3DSpeakerPosition);
+    engine.RegisterImportShim("_ZN4FMOD6System9playSoundE17FMOD_CHANNELINDEXPNS_5SoundEbPPNS_7ChannelE", Shim_System_playSound);
+    engine.RegisterImportShim("_ZN4FMOD6System9setOutputE15FMOD_OUTPUTTYPE", Shim_System_setOutput);
+
+    engine.RegisterImportShim("_ZN4FMOD7Channel11setCallbackEPF11FMOD_RESULTP12FMOD_CHANNEL25FMOD_CHANNEL_CALLBACKTYPEPvS5_E", Shim_Channel_setCallback);
+    engine.RegisterImportShim("_ZN4FMOD7Channel11setPriorityEi", Shim_Channel_setPriority);
+    engine.RegisterImportShim("_ZN4FMOD7Channel4stopEv", Shim_Channel_stop);
+    engine.RegisterImportShim("_ZN4FMOD7Channel7setMuteEb", Shim_Channel_setMute);
+    engine.RegisterImportShim("_ZN4FMOD7Channel9getPausedEPb", Shim_Channel_getPaused);
+    engine.RegisterImportShim("_ZN4FMOD7Channel9isPlayingEPb", Shim_Channel_isPlaying);
+    engine.RegisterImportShim("_ZN4FMOD7Channel9setPausedEb", Shim_Channel_setPaused);
+    engine.RegisterImportShim("_ZN4FMOD7Channel9setVolumeEf", Shim_Channel_setVolume);
+}

mpcore/src/main/cpp/emu/fmod_shims.h

@@ -0,0 +1,37 @@
+#pragma once
+
+#include "guest_engine.h"
+
+// FMOD Ex "Event System" API stubs (28 symbols: FMOD_EventSystem_Create,
+// FMOD_Memory_Initialize, and the EventSystem/Event/EventParameter/
+// EventCategory/EventGroup/ChannelGroup/DSP/System/Channel/Sound methods
+// this game's own dynsym relocations reference). No real audio - confirmed
+// this session that no arm64-v8a build of FMOD Ex (this specific, long-
+// deprecated Event System API generation, distinct from modern FMOD
+// Studio, which doesn't even have these classes) is available to link
+// against for real. See ARM64_TRANSLATION_LAYER.md.
+//
+// Every FMOD_RESULT-returning function here returns FMOD_OK (0) - the
+// GAME's own logic should proceed as if audio initialized successfully
+// rather than getting stuck on an audio-readiness gate, exactly the
+// "unresolved import silently returns 0" pattern this whole session has
+// been replacing elsewhere, except here 0 (FMOD_OK) genuinely IS the
+// semantically-correct "everything's fine" answer to give, not an
+// accidental one. Every `T**`-shaped output parameter (getEvent,
+// createSound, getSystemObject, ...) gets a small, valid, non-null FAKE
+// HANDLE (a real guest address, safe to store/pass to a later call, never
+// dereferenced beyond identity) instead of NULL, so calling code that
+// reasonably checks "did I get a real object back" doesn't bail out of
+// its own subsequent logic. Getters write plausible neutral defaults
+// (volume=1.0, paused=false, pitch=1.0, no active state flags) rather than
+// leaving output params untouched. Struct-shaped output parameters whose
+// EXACT size this file can't independently confirm (FMOD_EVENT_INFO,
+// FMOD_REVERB_PROPERTIES, FMOD_CREATESOUNDEXINFO) are deliberately left
+// untouched rather than guessed-and-memset, to avoid a wrong-sized write
+// overflowing into adjacent guest memory - the one well-known, stable FMOD
+// struct (FMOD_VECTOR - 3 floats, unchanged across every FMOD version)
+// does get zeroed. Callback registrations (Event::setCallback,
+// Channel::setCallback) accept and discard the guest callback pointer -
+// consistent with "no real audio ever plays," no event will ever fire to
+// invoke it.
+void RegisterFmodImportShims(GuestEngine& engine);

mpcore/src/main/cpp/emu/gles_shim.h

@@ -0,0 +1,54 @@
+#pragma once
+
+// Real GLES2 shim layer: forwards every gl* import the guest calls to the
+// REAL host GLES2 functions - not a translated/emulated GPU driver, just
+// argument marshaling (mechanically identical to the JNI shim: pointer args
+// G2H-translated, GLfloat args are raw-bit-reinterpreted since armeabi-v7a
+// uses the softfp calling convention - see import_shims.cpp's own top
+// comment). This works because the guest code calling these is executed
+// synchronously on whatever real host thread issued the CallGuestFunction
+// (the real engine's own GLThread, via nativeSurfaceCreated/nativeOnDrawFrame
+// - see real_native_offsets.h) - Android's own GLSurfaceView machinery has
+// ALREADY made a real, current EGL context current on that exact thread
+// before calling into any of this, so there is no separate EGL context to
+// stand up here; GL calls just land in the real, already-current context.
+//
+// Covers the full 142-function GLES2 core API (GLES2/gl2.h) minus 3 handled
+// by hand for pointer-indirection/return-ownership reasons (see
+// gles_shim.cpp): glGetString (returns a driver-owned string, copied into
+// guest heap memory rather than returning a raw host pointer),
+// glShaderSource (its `string` parameter is an ARRAY of guest pointers,
+// each element needs its own translation), glGetVertexAttribPointerv
+// (writes a pointer *value* into guest memory - needs H2G on the result,
+// not a direct G2H pass-through like every other pointer arg).
+//
+// Also covers AndroidBitmap_{getInfo,lockPixels,unlockPixels} (<android/
+// bitmap.h> - texture loading from Android Bitmap objects).
+//
+// Known correctness gap (semantic, not a crash): `glVertexAttribPointer`'s
+// and `glDrawElements`'s final pointer-shaped parameter is genuinely
+// dual-purpose in real OpenGL ES - a real pointer when no buffer is bound
+// (GL_ARRAY_BUFFER / GL_ELEMENT_ARRAY_BUFFER respectively), but a small
+// integer BYTE OFFSET into the currently-bound buffer object when one IS
+// bound (extremely common in real GLES2 rendering code - VBO-based
+// pipelines pass small offsets like 0/12/24 here, not pointers). The
+// generic "every pointer parameter is G2H-translated" rule these two share
+// with the other 137 functions is WRONG for the buffer-bound case: it
+// silently turns a small offset into a nonsense (but non-crashing) host
+// address instead of passing the offset through unchanged. Fixing this
+// properly needs this shim layer to track which buffer is currently bound
+// (mirroring glBindBuffer calls) and skip G2H when one is - not done yet;
+// documented rather than silently wrong. Low priority until real per-frame
+// draw calls are being exercised (this session got only as far as
+// GL-capability-detection calls, not actual drawing).
+#include "guest_engine.h"
+
+void RegisterGlesImportShims(GuestEngine& engine);
+
+// Diagnostic for the "nothing renders past the splash" investigation (see
+// ARM64_TRANSLATION_LAYER.md) - starts a detached background thread that
+// periodically logs how many real glClear/glDrawArrays/glDrawElements/
+// glUseProgram calls have happened, mirroring profiler.h's
+// StartProfileDumpThread pattern. Answers whether the render pipeline is
+// being exercised at all once the game reaches its post-splash state.
+void StartGlesCounterDumpThread();

mpcore/src/main/cpp/emu/guest_engine.h

@@ -0,0 +1,674 @@
+#pragma once
+
+// Core ARM32-on-ARM64 in-process CPU-level translation engine.
+// See /ARM64_TRANSLATION_LAYER.md for the design rationale, and this
+// session's desktop spike (scratchpad/spike_load.py, run against the real
+// native_lib/libapp.so) for what's been validated outside the NDK build
+// before this C++ was written.
+//
+// Design in one paragraph: libapp.so is loaded as an ET_DYN ELF32 whose own
+// preferred base is vaddr 0 (confirmed via readelf/pyelftools) - so instead
+// of inventing a separate guest/host address translation scheme, this
+// engine deliberately maps the image at guest address 0 too, backed by a
+// SINGLE contiguous host mmap covering [0, region_size). That makes
+// G2H(addr) = host_base + addr and H2G(ptr) = ptr - host_base plain pointer
+// arithmetic, and - more importantly - makes it the EXACT SAME arithmetic
+// every OFFSET macro already scattered through main.cpp/lan_event_injection.h
+// etc. already performs (APP_ADDR(offset) == (uintptr_t)libapp + offset).
+// None of that pre-existing reverse-engineering work needs to change.
+//
+// Hooking model: InstallTrampolineHook<Ret,Args...>(target, hookFn, name)
+// registers a Unicorn UC_HOOK_CODE at `target` (no byte-patching, unlike
+// this project's old armhook.cpp - Unicorn's hook fires BEFORE the real
+// instruction there is fetched, so nothing needs to be overwritten). The
+// dispatcher decodes r0-r3 into hookFn's real C++ argument types (pointer
+// args are G2H-translated automatically), calls hookFn (real host C++,
+// unchanged from what it always was), writes its return value into r0, and
+// sets PC=LR - i.e. from the guest's point of view the target function ran
+// and returned instantly. If hookFn wants to also run the REAL original
+// code (this project's universal "call orig_XXX(...) and use/return its
+// result" pattern), it calls the GuestFn this function returns, which
+// invokes a small trampoline built IN GUEST MEMORY (a verbatim copy of the
+// two displaced original instructions + a jump back to target+8, built the
+// same way this project's old InstallArmTrampolineHook built one in host
+// RWX memory) via CallGuestFunction - a real, separate, re-entrant Unicorn
+// call, so the rest of the original function actually executes.
+//
+// Multithreading model (added 2026-09-01, after a real on-device hang -
+// see ARM64_TRANSLATION_LAYER.md): a single Unicorn `uc_engine` holds ONE
+// CPU register set, so it cannot run more than one guest instruction stream
+// concurrently - real guest threads (spawned via pthread_create, see
+// emu/pthread_shim.*) each get their OWN `uc_engine*`, mapped onto the SAME
+// shared `host_region_` buffer via `uc_mem_map_ptr` (exactly mirroring how
+// real OS threads share one process's memory but have separate register/
+// stack state) and their own freshly-carved guest stack region (see
+// CarveThreadStack). All UC_HOOK_CODE registrations (import stubs, JNI/GLES
+// slots, trampoline hooks) are recorded in `hook_registrations_` at install
+// time and REPLAYED onto every new engine (ReplayHooksOnEngine) - Unicorn
+// hooks are per-engine, not shared. `uc_` itself is `thread_local`, and
+// every public entry point that might run on a new host thread
+// (CallGuestFunction) calls EnsureThreadEngine() first, so callers never
+// need to think about which engine is "current" - existing code that reads
+// `eng.uc()` automatically gets the right one for whichever thread it's
+// running on.
+
+#include <cstdint>
+#include <cstddef>
+#include <cstring>
+#include <string>
+#include <mutex>
+#include <atomic>
+#include <vector>
+#include <unordered_map>
+#include <dlfcn.h>
+#include <unicorn/unicorn.h>
+#include "guest_types.h"
+#include "guest_heap.h"
+#include "../util/util.h"
+
+// A resolved-and-loaded import shim: called when guest code reaches a GOT
+// slot's stub address instead of a real function (see import_shims.h/.cpp
+// and emu/gles_shim.h/.cpp for the actual implementations). Args are raw
+// r0-r3 plus `sp` (the entry stack pointer, needed to read AAPCS32 stack
+// args for any import with more than 4 parameters - e.g. most GLES2
+// functions - via engine.ReadIncomingArg()); return is written into r0.
+// Marshaling to/from real host types is the shim's own job (same contract
+// as a hook callback).
+using ImportShimFn = uint32_t (*)(class GuestEngine& engine, uint32_t r0, uint32_t r1, uint32_t r2, uint32_t r3, uint32_t sp);
+
+class GuestEngine {
+public:
+    static GuestEngine& Instance();
+
+    // Loads libapp.so from `path` (a real file - see app module's asset
+    // extraction for how it gets there since it can no longer be a normal
+    // jniLibs/armeabi-v7a entry the loader dlopen()s). Returns false and
+    // logs on any failure (bad ELF, mmap failure, etc.) - this project's
+    // existing convention (see util/util.cpp's Log) of "log and return
+    // false, never abort/crash the host process on a load failure".
+    bool LoadImage(const char* path);
+
+    // Loads a SEPARATE ARM32 ELF32 .so image alongside whatever LoadImage
+    // already loaded, for cases that need a real, independently-compiled
+    // artifact running under this engine without disturbing libapp.so's own
+    // state (2026-09-16, ARM64_TRANSLATION_LAYER.md's "isolated
+    // std::ostringstream repro" test - see emu/ostream_repro_test.cpp for
+    // the actual caller). Deliberately NOT a second call to LoadImage:
+    // MapSegments is a single-image design end to end (host_region_ is one
+    // mmap sized around exactly one image's own image_end_, and depends on
+    // the loaded image's OWN preferred ET_DYN base being guest address 0 -
+    // see this class's own top comment) - calling it twice would re-mmap
+    // host_region_ out from under the already-loaded primary image, losing
+    // its heap/hooks/relocations entirely. Instead, this carves space for
+    // the WHOLE second image out of the existing AllocMmap() arena (already
+    // part of the SAME host_region_ every engine thread maps - see
+    // AllocMmap's own comment) at whatever guest address that arena's bump
+    // allocator hands out, then repeats MapSegments/ProcessRelocations'
+    // logic with a real, non-zero BIAS added to every relocation (the
+    // primary loader gets away with skipping R_ARM_RELATIVE entirely
+    // because its own bias is always exactly 0 - see ProcessRelocations'
+    // own comment - this one actually adds `base` to each one). External
+    // symbol references resolve through the EXACT SAME
+    // ResolveOrCreateImportStub/RegisterImportShim table the primary
+    // image's own imports already use, so this needs no new engine-side
+    // shim plumbing by itself - whatever real shims (or "unresolved import,
+    // log once, return 0" fallbacks) libapp.so's loading already registered
+    // apply here unchanged. This is deliberately NOT a general-purpose
+    // second dynamic linker (no DT_NEEDED handling, no symbol versioning,
+    // no PLT-lazy-binding tricks) - just enough to run one small,
+    // self-contained test artifact end to end.
+    //
+    // `entrySymbol` is looked up in the image's own .dynsym via its section
+    // headers (survives a normal `strip`, unlike .symtab - see this
+    // function's own .cpp comment for why section headers rather than
+    // DT_SYMTAB are used for this specific lookup). Returns the resolved
+    // guest address (Thumb bit already included, same convention as every
+    // other resolved address in this engine) ready to hand straight to
+    // CallGuestFunction, or 0 on any failure (bad ELF, arena exhaustion,
+    // symbol not found - all logged).
+    // Loads an additional guest ELF alongside the primary image and records
+    // everything it EXPORTS, so a later import of one of those names resolves
+    // to the real code instead of a shim (see ResolveOrCreateImportStub).
+    //
+    // Pass entrySymbol = nullptr when the caller only wants the library loaded
+    // and does not need one specific address back - which is the case for the
+    // game's own FMOD libraries, whose entry points are reached through
+    // libapp.so's ordinary imports rather than by name from the host.
+    // Returns the entry symbol's address, or 1 for "loaded, no entry requested",
+    // or 0 on failure.
+    GuestAddr LoadSecondaryImage(const char* path, const char* entrySymbol);
+
+    // Loads the guest libraries that sit alongside the primary image in the
+    // same directory - currently the game's own FMOD. Called from LoadImage at
+    // the one point where it is both possible and still useful; see the call
+    // site's own comment for why the ordering is not negotiable.
+    void LoadSiblingLibraries(const char* primaryImagePath);
+
+    bool loaded() const { return host_region_ != nullptr; }
+
+    // ---- Address translation ----
+    // Both are plain pointer arithmetic (see class comment) - cheap enough
+    // to call at every struct-field access site, matching how this
+    // project's existing APP_ADDR(offset) macro is already used everywhere.
+    void* G2H(GuestAddr addr) const {
+        // host_region_ is a single contiguous mmap of exactly region_size_
+        // bytes covering every real arena (image/heap/trampoline/import-
+        // stub/misc-stub/control/thread-stacks) - any addr past that is
+        // definitely not a real guest address. Left unchecked, this used to
+        // be plain pointer arithmetic handed straight to whatever the
+        // caller does next (memcpy, strlen, direct struct access...) - one
+        // of this engine's own Shim_*/Impl_* functions handed a garbage
+        // guest-supplied pointer (e.g. Shim_time()'s tPtr) would compute a
+        // wild HOST pointer and crash the entire process with a real
+        // SIGSEGV, not a graceful, recoverable guest-level fault the way a
+        // bad access from actual emulated ARM32 code would (that path goes
+        // through Unicorn's own protection and mem_fault_hook_cb instead -
+        // this one bypasses it entirely, since it's host C++ dereferencing
+        // directly). Confirmed live this session via a symbolicated
+        // tombstone: Shim_time() got a garbage tPtr, memcpy'd 4 bytes
+        // through G2H(tPtr), and took down the whole app. G2H() is the
+        // single choke point for all such guest-pointer translation
+        // (250+ call sites across emu/*.cpp) - bounds-checking it here
+        // closes the entire bug class at once instead of guarding each
+        // call site individually.
+        if (addr >= region_size_) {
+            LogOutOfRangeG2H(addr);
+            static thread_local uint8_t scratch[64];
+            return scratch;
+        }
+        return host_region_ + addr;
+    }
+    GuestAddr H2G(const void* hostPtr) const {
+        return static_cast<GuestAddr>(reinterpret_cast<const uint8_t*>(hostPtr) - host_region_);
+    }
+    // True if `hostPtr` actually falls inside this engine's guest-backed
+    // region - H2G() on a pointer that DOESN'T (e.g. a real driver-owned
+    // buffer, like an AndroidBitmap pixel buffer - see gles_shim.cpp) would
+    // silently produce a garbage/wraparound "guest address" rather than an
+    // error, so callers that got a pointer from somewhere OTHER than this
+    // engine's own G2H/heap should check this before calling H2G.
+    bool IsHostPointerInRegion(const void* hostPtr) const {
+        auto p = reinterpret_cast<const uint8_t*>(hostPtr);
+        return p >= host_region_ && p < host_region_ + region_size_;
+    }
+    // host_region_ itself, for code that wants the old-style
+    // "(uintptr_t)libapp + offset" spelling unchanged (see main.h's
+    // APP_ADDR macro, redefined in terms of this).
+    uint8_t* image_host_base() const { return host_region_; }
+
+    // One-past-the-end guest address of the loaded ELF image's own PT_LOAD
+    // segments (page-aligned) - any guest address >= this is one of THIS
+    // engine's own arenas (heap/trampoline/import-stub/misc-stub/thread-
+    // stacks), never real libapp.so code, useful for diagnosing a function
+    // pointer the guest passes around (e.g. pthread_shim.cpp's
+    // pthread_create logging) that turns out to point at one of our own
+    // stubs instead of real code.
+    GuestAddr image_end() const { return image_end_; }
+
+    // ---- Guest heap (for malloc/free/calloc shims and any hook body that
+    // still wants to allocate guest-visible memory directly, e.g.
+    // InjectSyntheticEvent's RaceEvent/CashReward/FakeActor objects) ----
+    GuestHeap& heap() { return heap_; }
+
+    // Bump-allocates from a small, SEPARATE, never-freed arena reserved for
+    // permanent, safety-critical control structures - currently just the
+    // guest JNIEnv/JavaVM (see jni_shim.cpp's BuildGuestJNIEnv/
+    // BuildGuestJavaVM). Deliberately NOT part of heap() (GuestHeap backs
+    // the guest program's own uncontrolled malloc/free churn - see
+    // guest_heap.h's class comment for the corruption this session traced a
+    // real crash to) - anything allocated here is meant to live for the
+    // rest of the process and must never be reachable by a stray guest
+    // free()/overflow in the general heap. No Free() counterpart on
+    // purpose: nothing here is ever supposed to go away.
+    GuestAddr AllocPermanent(uint32_t size);
+
+    // Bump-allocates from a dedicated arena backing real mmap() (see
+    // libc_shims.cpp's Shim_mmap) for the anonymous-mapping case. Same
+    // "never freed" simplicity as AllocPermanent (munmap() stays a no-op -
+    // no evidence yet that guest code depends on reclaiming mmap'd space),
+    // but page-granular and its own cursor/mutex since mmap allocations are
+    // arbitrarily larger than AllocPermanent's small control structures.
+    // Returns 0 (and logs) if the arena is exhausted.
+    GuestAddr AllocMmap(uint32_t length);
+
+    // ---- Calling into guest code from host C++ ----
+    // Up to 4 integer/pointer args go in r0-r3; any beyond that are pushed
+    // onto the guest stack per AAPCS32 (args[4] at [sp+0], args[5] at
+    // [sp+4], ...) - needed for real JNI entry points like
+    // nativeSurfaceChanged(env,thiz,gl10,w,h) (5 args) and arbitrary-arity
+    // JNI Call*Method calls (see emu/jni_shim.*).
+    uint32_t CallGuestFunction(GuestAddr target, const uint32_t* args, int argCount);
+    // Convenience overload for the common <=4-arg case (existing call sites).
+    uint32_t CallGuestFunction(GuestAddr target, uint32_t a0 = 0, uint32_t a1 = 0,
+                                uint32_t a2 = 0, uint32_t a3 = 0) {
+        uint32_t args[4] = {a0, a1, a2, a3};
+        return CallGuestFunction(target, args, 4);
+    }
+
+    // The r1 half of the r0:r1 pair a guest function declared to return a
+    // 64-bit value (long/double, per AAPCS32) left behind at the end of the
+    // MOST RECENT CallGuestFunction() call on this thread - call this
+    // immediately after CallGuestFunction() returns, before making any other
+    // guest call on the same thread (a nested/reentrant CallGuestFunction
+    // would overwrite it). Added for jni_shim.cpp's RegisterNatives reverse
+    // bridge (TrampolineBodyWide) to support Java-calls-guest native methods
+    // declared to return long/double, matching the same r0:r1-pair handling
+    // already used for the forward (Call*Method) direction - see
+    // jni_shim.cpp's InvokeCall.
+    uint32_t LastCallHighWord() const { return t_state_.lastCallHiWord; }
+
+    // Reads incoming argument N (0-based) of the function whose UC_HOOK_CODE
+    // callback is currently executing - r0-r3 for N<4, else the guest stack
+    // at the point of entry (sp is the entry SP, as seen by the hook
+    // callback). Used by the JNI shim's dispatcher (jni_shim.cpp) to read
+    // arguments beyond the 4 general-purpose registers.
+    uint32_t ReadIncomingArg(int n, uint32_t r0, uint32_t r1, uint32_t r2, uint32_t r3, uint32_t sp) const {
+        switch (n) {
+            case 0: return r0;
+            case 1: return r1;
+            case 2: return r2;
+            case 3: return r3;
+            default: {
+                uint32_t v = 0;
+                memcpy(&v, G2H(sp + (uint32_t)(n - 4) * 4), 4);
+                return v;
+            }
+        }
+    }
+
+    // ---- Hooking ----
+    // Builds a guest-memory trampoline (verbatim copy of target's first two
+    // instruction words + a jump back to target+8 - REQUIRES those two
+    // words to be position-independent, exactly the same precondition this
+    // project's old InstallArmTrampolineHook already required and every
+    // existing hook site was already manually verified against via IDA
+    // disasm before hooking) and registers a UC_HOOK_CODE at `target`.
+    // Returns the trampoline's guest address (0 on failure) - wrap it in a
+    // GuestFn<Ret,Args...> to get an "orig_XXX"-shaped callable.
+    GuestAddr InstallTrampolineHookRaw(GuestAddr target, void (*dispatch)(GuestEngine&, void*),
+                                        void* userData, const char* debugName);
+
+    // ---- Imports ----
+    void RegisterImportShim(const char* symbolName, ImportShimFn fn);
+
+    // Same registration role as RegisterImportShim, but for symbols that
+    // are semantically DATA (typeinfo objects, vtables), not callable
+    // functions - e.g. `_ZTIi` (int's type_info) is referenced as `&_ZTIi`
+    // and read through directly (vtable-pointer field, name-pointer field),
+    // never called. Resolving a data symbol through the normal code-stub
+    // path (AllocCodeStub) would hand out an address in the misc-stub arena
+    // holding a 4-byte UC_HOOK_CODE placeholder - reading struct fields
+    // through that is garbage, the same "read/write through a wrong-shaped
+    // address" bug class this session already traced a real corruption to.
+    // `address` must be a real, pre-built guest address (see
+    // rtti_shims.cpp for the typeinfo objects this backs) - checked in
+    // ResolveOrCreateImportStub BEFORE falling back to a code stub.
+    void RegisterDataSymbol(const char* symbolName, GuestAddr address);
+
+    // Reverse of RegisterDataSymbol: which symbol, if any, was given this
+    // address. Exists so a shim that cannot honour a request can NAME what it
+    // was asked for instead of printing a bare arena address - the facet
+    // addresses handed out by AllocPermanent mean nothing on their own, and
+    // resolving one otherwise costs a rebuild and a reproduction (see
+    // Shim_use_facet). Linear scan: this is an error path only.
+    // Returns nullptr when the address is not a registered data symbol.
+    const char* NameForDataSymbol(GuestAddr address) const;
+
+    // Address of a symbol defined by a secondary guest image (see
+    // LoadSecondaryImage), or 0 if no loaded image exports that name. Lets
+    // host-side JNI entry points forward into real guest code - see
+    // game_lifecycle_stubs_extra2.cpp's FMOD audio bridge.
+    GuestAddr LookupSecondaryExport(const char* symbolName) const;
+
+    // Logs once when execution first reaches `addr`, without altering control
+    // flow - a pure observation point, unlike InstallTrampolineHookRaw which
+    // displaces instructions. Used to answer "which of these N places produced
+    // the error code" by watching every candidate at once instead of reasoning
+    // about which one is reachable.
+    //
+    // `label` is copied and used verbatim in the log line.
+    void WatchGuestAddress(GuestAddr addr, const char* label);
+
+    // True if `addr` lies inside ANY loaded guest image - the primary one or
+    // a sibling loaded by LoadSecondaryImage. Callers that need to tell "real
+    // guest code" from "one of this engine's own arenas" must ask this rather
+    // than comparing against image_end(), which only ever described the
+    // primary image and silently rejected every sibling.
+    bool IsGuestImageCode(GuestAddr addr) const;
+
+    // Registers a callback GuestEngine invokes exactly once per LoadImage
+    // call, right after MapSegments succeeds (so host_region_/
+    // AllocPermanent are usable) but strictly BEFORE ProcessRelocations
+    // resolves any GOT slot - lets a caller (rtti_shims.cpp's
+    // SetupRttiDataSymbols) build real guest-memory-backed data objects and
+    // RegisterDataSymbol() them before anything could reference them. Kept
+    // as a callback rather than a hard dependency so guest_engine.h/.cpp
+    // doesn't need to know rtti_shims.h exists - main.cpp wires the two
+    // together by calling this before engine.LoadImage(path).
+    using DataSymbolSetupFn = void (*)(GuestEngine&);
+    void RegisterDataSymbolSetup(DataSymbolSetupFn fn) { data_symbol_setup_fns_.push_back(fn); }
+
+    // Generic building block behind both the ELF import-stub resolver above
+    // and jni_shim.cpp's per-slot JNIEnv stubs: carves one fresh guest
+    // address out of a small reserved arena and registers a UC_HOOK_CODE
+    // there directly (no trampoline/displaced-instruction copying needed,
+    // unlike InstallTrampolineHookRaw - there's no real instruction bytes
+    // at a stub address, it only ever exists to be intercepted).
+    GuestAddr AllocCodeStub(uc_cb_hookcode_t callback, void* userData);
+
+    // Allocates `size` bytes of guest memory that may be EXECUTED, out of the
+    // trampoline arena. AllocPermanent cannot be used for code: it carves from
+    // the control arena, which CreateConfiguredEngine maps read-write only
+    // (task #54 - an executable mapping makes every write to it pay QEMU's
+    // notdirty_write path, and making the control arena executable again cost
+    // a measured ~4s of load time). Returns 0 if the arena is exhausted.
+    GuestAddr AllocGuestCode(uint32_t size);
+
+    // Resolves `symbolName` to a real, guest-callable address, creating a
+    // fresh import stub (via AllocCodeStub) the first time it's asked for
+    // and caching it thereafter - the same path a real ELF PLT import goes
+    // through, but callable directly by name for symbols that were never
+    // themselves a real import (2026-09-18: eglGetProcAddress's own shim
+    // needs this - some real games resolve even core, non-optional
+    // functions like eglSwapBuffers this way instead of a direct import -
+    // see libc_shims.cpp's own Shim_eglGetProcAddress). Was private; made
+    // public for that use case, no behavior change.
+    GuestAddr ResolveOrCreateImportStub(const std::string& symbolName);
+
+    // Diagnostic: classifies a guest address by which arena it falls into
+    // (real image code, heap, trampoline/import-stub/misc-stub/control,
+    // thread-stacks, or fully out of range) - and, for the import-stub
+    // arena specifically, which registered symbol's stub it is (reverse
+    // lookup over import_stub_by_symbol_, a small map - fine for a rare
+    // diagnostic call, not a hot path). Added to investigate a guest
+    // function pointer (pthread_create's start_routine) landing on one of
+    // this engine's own stub addresses instead of real ARM32 code - see
+    // pthread_shim.cpp's own use and ARM64_TRANSLATION_LAYER.md.
+    std::string DescribeAddress(GuestAddr addr) const;
+
+    // The CURRENT host thread's own guest CPU - see class comment's
+    // "Multithreading model". Never null when called from inside a
+    // dispatch callback (Unicorn always hands the callback the engine it
+    // fired on) or after EnsureThreadEngine() has run for this thread.
+    uc_engine* uc() const { return t_state_.uc; }
+
+    // Guarantees the CALLING host thread has its own `uc_engine*` (mapped
+    // onto the shared guest memory, with every hook replayed) and its own
+    // guest stack region, creating them on first use if needed. Called
+    // automatically by CallGuestFunction, so ordinary callers never need to
+    // call this themselves - exposed mainly for pthread_shim.cpp, which
+    // must call it as the very first thing on a freshly spawned host thread
+    // before that thread can run any guest code at all.
+    void EnsureThreadEngine();
+
+    // Tears down everything EnsureThreadEngine (and any nested-call engine)
+    // set up for the CALLING host thread, returning its guest stacks to the
+    // arena for reuse. Must be called by any thread that created an engine
+    // and is about to exit - pthread_shim's thread body does. Safe to call on
+    // a thread that never had one.
+    void ReleaseThreadEngine();
+
+    // Reserved, never-fetched guest PC used as the "return to caller"
+    // target for every CallGuestFunction invocation (see .cpp for why a
+    // fixed constant is safe to reuse across nested calls).
+    static constexpr GuestAddr kCallReturnSentinel = 0xFFFFFFF0u;
+
+    // True once any CallGuestFunction call has hit a fault-class uc_err
+    // (unmapped/protected memory access, invalid instruction, ...) - see
+    // CallGuestFunction's own comment for why every subsequent call then
+    // refuses to run instead of re-entering guest code whose SHARED memory
+    // (host_region_, one buffer for every thread - see class comment) may
+    // already be corrupted.
+    bool crashed() const { return crashed_.load(std::memory_order_relaxed); }
+
+private:
+    GuestEngine() = default;
+
+    bool MapSegments(const uint8_t* fileData, size_t fileSize);
+    bool ProcessRelocations(const uint8_t* fileData, size_t fileSize);
+    void ReplayHooksOnEngine(uc_engine* newUc);
+    // Fix (2026-09-16, ARM64_TRANSLATION_LAYER.md - uc_emu_start()
+    // reentrancy hang). Everything EnsureThreadEngine() used to do inline to
+    // stand up a brand-new uc_engine* - uc_open, mapping host_region_ onto
+    // it, guard-page/RELRO protection, VFP/NEON enable, ReplayHooksOnEngine,
+    // the MiscStubDispatch/mem_fault_hook_cb/profiling hooks, and every
+    // diagnostic one-off probe hook - factored out so BOTH the thread's
+    // primary engine (EnsureThreadEngine) and any per-depth nested engine
+    // (GetOrCreateNestedEngine) get the exact same setup. Returns nullptr on
+    // any hard failure (logs its own reason). Deliberately does NOT touch
+    // t_state_ or carve a guest stack - callers own that part, since a
+    // nested engine shares the primary engine's existing stack range rather
+    // than getting its own (see CallGuestFunction's SP-reuse logic).
+    uc_engine* CreateConfiguredEngine();
+    // Returns (creating on first use) the uc_engine* this thread uses for
+    // CallGuestFunction calls at the given reentrancy depth (>=1; depth 0
+    // always uses t_state_.uc directly, see CallGuestFunction) - see
+    // ThreadState::nestedEngines' own comment. Returns nullptr and logs if
+    // depth exceeds kMaxNestedEngines.
+    uc_engine* GetOrCreateNestedEngine(uint32_t depth);
+    // The ONE UC_HOOK_CODE ever registered over the whole misc-stub arena
+    // (see EnsureThreadEngine) - looks up the real {callback, userData} for
+    // the faulting address in misc_stub_dispatch_table_ via O(1) array
+    // indexing and delegates to it. Static (matches uc_cb_hookcode_t's
+    // plain-function-pointer signature - no `this` to pass) - reaches state
+    // via GuestEngine::Instance(), same singleton-access pattern used
+    // throughout this file's own free-function callbacks. See
+    // misc_stub_arena_start_'s own comment (above) for why this exists.
+    static void MiscStubDispatch(uc_engine* uc, uint64_t address, uint32_t size, void* userData);
+    // G2H()'s out-of-range guard - see G2H()'s own comment. Rate-limited
+    // (first kMaxOutOfRangeG2HLogs occurrences, then a final "suppressed"
+    // notice and silence) so a call site that gets hit in a loop can't
+    // flood logcat; different bad addresses across those occurrences
+    // likely mean different underlying bugs, so this logs every one of
+    // them up to the cap rather than a single "logged once ever" flag.
+    void LogOutOfRangeG2H(GuestAddr addr) const;
+    // Carves one fresh, never-reused kThreadStackSize-byte region out of the
+    // shared thread-stacks arena and returns its TOP (highest usable
+    // address) - 0 if the arena is exhausted (see kMaxGuestThreads).
+    GuestAddr CarveThreadStack();
+
+    // Cap on ThreadState::nestedEngines below - see its own comment. Purely
+    // a safety net (mirrors kMaxCallIterations' "not an expected limit"
+    // philosophy), not a value callers should ever need to approach.
+    static constexpr uint32_t kMaxNestedEngines = 8;
+
+    // Per-host-thread state - see class comment's "Multithreading model".
+    // `static thread_local` because GuestEngine is a singleton (one logical
+    // instance) but each real host thread needs to see its OWN CPU/stack -
+    // this is the ONLY thing that needs to be per-thread; host_region_,
+    // heap_, and every *_cursor_/*_end_ arena boundary below are genuinely
+    // shared (real threads share one process's memory, which is exactly
+    // what host_region_ already models).
+    struct ThreadState {
+        uc_engine* uc = nullptr;
+        GuestAddr stackBase = 0, stackTop = 0;
+        // R1 as it stood the instant the most recent CallGuestFunction() on
+        // THIS thread finished (before the reentrancy save/restore at the
+        // end of that function overwrites it with the outer call's value) -
+        // the high word of a 64-bit (long/double) guest return, which the
+        // public CallGuestFunction() API itself only ever exposes r0 of. See
+        // LastCallHighWord()'s own comment.
+        uint32_t lastCallHiWord = 0;
+        // Diagnostic (2026-09-16, ARM64_TRANSLATION_LAYER.md - synthetic
+        // unit test confirmed a reentrant CallGuestFunction() call, invoked
+        // from within a UC_HOOK_CODE callback that's itself running during
+        // an already-active uc_emu_start() on this thread's engine, hangs
+        // (a nested uc_emu_start() on the same uc_engine* is not safely
+        // reentrant in this Unicorn build). >0 means CallGuestFunction is
+        // currently executing on this thread - lets CallGuestFunction log
+        // when it's entered reentrantly, to check whether the REAL game
+        // code path that leads to the sub_43FDE0 crash ever actually
+        // triggers this exact mechanism.
+        uint32_t callDepth = 0;
+        // Fix (2026-09-16, ARM64_TRANSLATION_LAYER.md - the confirmed
+        // uc_emu_start() reentrancy hang). One lazily-created uc_engine* per
+        // reentrancy depth beyond the outermost (index 0 here == depth 1,
+        // since depth 0 always uses `uc` above) - nestedEngines[callDepth-1]
+        // is the engine a CallGuestFunction() invoked from within a
+        // UC_HOOK_CODE callback (itself running during an already-active
+        // uc_emu_start() on `uc`) runs on, instead of re-entering `uc`
+        // itself. Created once per depth per thread and kept for the
+        // thread's lifetime (same "leaked deliberately, cheap to keep"
+        // pattern as `uc` itself - see EnsureThreadEngine), not
+        // recreated per call. kMaxNestedEngines is a generous safety cap
+        // (deepest depth actually observed live was 2), not an expected
+        // limit - see GetOrCreateNestedEngine.
+        uc_engine* nestedEngines[kMaxNestedEngines] = {};
+        // Fix (2026-09-16, ARM64_TRANSLATION_LAYER.md - the WRITE_PROT
+        // fault @0xac77e8/sub_3D58BC bisection). Each depth's own DEDICATED
+        // stack range, top address only (base = top - kStackSize, same
+        // convention as stackTop/stackBase above) - carved via
+        // CarveThreadStack() the same way a real host thread's own stack
+        // is, the first time that depth is used. Without this, a depth>0
+        // call's SP defaults to "this engine's own SP minus a small gap",
+        // which - since nestedEngines[i] is a SEPARATE engine with its OWN
+        // independent SP, unrelated to how deep the OUTER (suspended)
+        // frame actually is in ITS stack - always lands near the SAME
+        // small window close to stackTop, REGARDLESS of depth or which
+        // outer frame triggered it. Confirmed live: an outer frame that
+        // itself happens to run near the top of its own thread's stack
+        // (sub_75E40, entered only a few frames deep) collided directly
+        // with reentrant JNI/misc-stub and pthread_once (sub_87b968/
+        // sub_88ccd0) calls all anchored at that same stackTop-adjacent
+        // window, corrupting the outer frame's own saved-register stack
+        // slot. A dedicated per-depth stack (same isolation principle
+        // nestedEngines already gives the CPU register file) makes this
+        // physically impossible - see GetOrCreateNestedEngine.
+        GuestAddr nestedStackTop[kMaxNestedEngines] = {};
+    };
+    static thread_local ThreadState t_state_;
+
+    uint8_t* host_region_ = nullptr; // guest address 0 == this host pointer
+    uint32_t region_size_ = 0;
+    GuestAddr image_end_ = 0;
+    // PT_GNU_RELRO range (page-aligned, conservatively rounded inward - see
+    // MapSegments' own comment), mprotect'd UC_PROT_READ on every engine
+    // after relocations write into it. 0 size = not present in this ELF /
+    // rounding left nothing to protect - skip.
+    GuestAddr relro_start_ = 0;
+    uint32_t relro_size_ = 0;
+    GuestAddr heap_base_ = 0, heap_end_ = 0;
+    GuestAddr trampoline_cursor_ = 0, trampoline_end_ = 0;
+    GuestAddr import_stub_cursor_ = 0, import_stub_end_ = 0;
+    GuestAddr misc_stub_cursor_ = 0, misc_stub_end_ = 0; // AllocCodeStub arena (jni_shim.cpp's 233 slots, etc.)
+    // Fixed start of the misc-stub arena (misc_stub_cursor_ itself moves as
+    // a bump pointer, so a separate fixed value is needed to compute a
+    // stub's index later) - set once, at the same place misc_stub_cursor_
+    // gets its own one-time initial value. See MiscStubDispatch's own
+    // comment (guest_engine.cpp) for why this exists: 2026-09-06,
+    // ARM64_TRANSLATION_LAYER.md - consolidating ~600+ individually
+    // Unicorn-registered UC_HOOK_CODE hooks (one per AllocCodeStub call)
+    // into one hook + an O(1) array lookup, after confirming (both
+    // empirically, via a 284x isolated-vs-real-context benchmark gap, and
+    // mechanistically, via Unicorn's own hook storage being a linked list
+    // walked per translated block - third_party/unicorn/include/uc_priv.h)
+    // that registering hundreds of individual hooks was a real, engine-wide
+    // performance tax paid on every block anywhere in the address space.
+    GuestAddr misc_stub_arena_start_ = 0;
+    GuestAddr control_cursor_ = 0, control_end_ = 0; // AllocPermanent arena - see its own comment
+    GuestAddr thread_stacks_cursor_ = 0, thread_stacks_end_ = 0; // CarveThreadStack arena
+    GuestAddr mmap_cursor_ = 0, mmap_end_ = 0; // AllocMmap arena - see its own comment
+
+    std::mutex thread_stacks_mutex_; // guards thread_stacks_cursor_ and the free list below
+    // Stacks handed back by ReleaseThreadEngine, ready to be reused.
+    //
+    // Without this the arena was a one-way bump allocator: every guest thread
+    // that finished kept its stack forever, and so did every nested-call
+    // engine, so a long session simply ran out. Confirmed live - the game
+    // created its race thread, CarveThreadStack returned 0, the thread's
+    // start routine never ran, and the race rendered as a black screen.
+    std::vector<GuestAddr> thread_stack_free_list_;
+    std::mutex control_mutex_;       // guards control_cursor_
+    std::mutex mmap_mutex_;          // guards mmap_cursor_
+
+    GuestHeap heap_;
+
+    std::unordered_map<std::string, ImportShimFn> registered_shims_;
+    std::unordered_map<std::string, GuestAddr> registered_data_symbols_; // see RegisterDataSymbol
+    // Symbols DEFINED by secondary guest images (see LoadSecondaryImage).
+    // Consulted by ResolveOrCreateImportStub ahead of the shim table, so that
+    // once the game's real ARM32 FMOD is loaded its own entry points win over
+    // the no-op stand-ins fmod_shims.cpp registers.
+    std::unordered_map<std::string, GuestAddr> secondary_image_exports_;
+    // [base, base+span) for each image LoadSecondaryImage has loaded.
+    struct LoadedImageRange { GuestAddr base; uint32_t span; };
+    std::vector<LoadedImageRange> secondary_image_ranges_;
+    std::vector<DataSymbolSetupFn> data_symbol_setup_fns_; // see RegisterDataSymbolSetup
+    std::unordered_map<std::string, GuestAddr> import_stub_by_symbol_; // dedupe: one stub per symbol name
+    std::unordered_map<GuestAddr, ImportShimFn> shim_by_stub_addr_;
+    std::unordered_map<GuestAddr, std::string> unresolved_stub_names_; // for shims we don't implement - logged once, then return 0
+
+    struct TrampolineHookEntry {
+        void (*dispatch)(GuestEngine&, void*);
+        void* userData;
+        std::string debugName;
+    };
+
+    // Every UC_HOOK_CODE ever installed (import stubs, JNI/GLES slots,
+    // trampoline hooks) - replayed onto each new guest thread's own engine
+    // by ReplayHooksOnEngine, since Unicorn hooks are per-engine. Installed
+    // once, during single-threaded setup (before any guest thread exists),
+    // but mutex-guarded anyway since EnsureThreadEngine (reading this list)
+    // could in principle race a very-early AllocCodeStub call.
+    struct HookRegistration {
+        uc_cb_hookcode_t callback;
+        void* userData;
+        GuestAddr addr;
+    };
+    std::vector<HookRegistration> hook_registrations_;
+    std::mutex hook_registrations_mutex_;
+
+    // AllocCodeStub's own dispatch table (see MiscStubDispatch,
+    // guest_engine.cpp) - one entry per stub, in allocation order, which
+    // equals address order since misc_stub_cursor_ is a pure sequential
+    // 4-byte bump allocator with no frees (same guarantee hook_registrations_
+    // already relied on for its own replay). Index = (addr -
+    // misc_stub_arena_start_) / 4. Replaces per-stub uc_hook_add calls with
+    // one array lookup - see misc_stub_arena_start_'s own comment for why.
+    struct MiscStubEntry {
+        uc_cb_hookcode_t callback;
+        void* userData;
+    };
+    // Lock-free on the read side (2026-09-19, task #56). This table is hit on
+    // EVERY shim crossing - measured at ~170,000/sec during gameplay on the
+    // Xiaomi 14, from several threads - and taking a std::mutex there taxed
+    // the exact thing being measured. A fixed array plus an atomic published
+    // count removes it safely: the arena is only kMiscStubArenaSize/4 stubs
+    // wide by construction (AllocCodeStub bump-allocates 4 bytes each and
+    // refuses past the end), entries are appended and never removed or
+    // rewritten, and a writer fills its slot BEFORE publishing the new count
+    // with release ordering. A reader that acquires the count therefore sees
+    // a fully-written entry. The mutex stays for the append side, which runs
+    // a few hundred times at startup.
+    static constexpr size_t kMaxMiscStubs = 16 * 1024 / 4;
+    MiscStubEntry misc_stub_dispatch_table_[kMaxMiscStubs] = {};
+    std::atomic<size_t> misc_stub_dispatch_count_{0};
+    std::mutex misc_stub_dispatch_table_mutex_; // append side only
+
+    // See crashed()'s own comment. Global (not per-thread) on purpose - a
+    // fault on ANY thread means the ONE shared host_region_ every thread's
+    // engine maps may be corrupted for everyone, not just the thread that
+    // happened to hit it.
+    std::atomic<bool> crashed_{false};
+    std::atomic<bool> crashed_logged_{false}; // so the "refusing to run" log fires once, not on every retry
+    // Counter (was a one-shot bool) for CallGuestFunction's 2026-09-16
+    // reentrancy probe - the first log-once version only ever showed the
+    // FIRST reentrant call, which turned out (2026-09-16, same-day
+    // follow-up) to be a harmless trivial stub. Now logs every occurrence
+    // up to reentrancy_log_cap_ (see CallGuestFunction), so occurrences
+    // CLOSER to an actual crash are visible too - capped, not fully
+    // unconditional, because a runaway retry loop (the exact synthetic-test
+    // scenario this probe was built to detect) re-enters at ~6000 calls/sec
+    // against the SAME target and would otherwise flood logcat's ring
+    // buffer with nothing else visible within milliseconds.
+    std::atomic<int> reentrancy_log_count_{0};
+    static constexpr int kReentrancyLogCap = 200;
+};
+
+// Diagnostic for the render-stall investigation (see
+// ARM64_TRANSLATION_LAYER.md's "Periodic live instruction-trace dump" plan)
+// - starts a detached background thread that periodically logs the last N
+// executed guest blocks in true execution order (not a sampled histogram
+// like profiler.h's own dump), so a loop that never faults (and so never
+// hits CallGuestFunction's own fault-branch trace dump) can still be traced.
+void StartLiveTraceDumpThread();

mpcore/src/main/cpp/emu/guest_fn.h

@@ -0,0 +1,144 @@
+#pragma once
+
+// Typed calling-convention layer on top of GuestEngine's raw
+// CallGuestFunction/InstallTrampolineHookRaw. This is what lets the rest of
+// mpcore's existing hook code (main.cpp, lan_event_injection.h, ...) keep
+// its original shape almost unchanged: a "resolved function pointer" this
+// codebase already declares as e.g.
+//   typedef void* (*RaceEventCtorFn)();
+//   static RaceEventCtorFn RaceEventCtor = (RaceEventCtorFn)APP_ADDR(OFFSET);
+// becomes
+//   static GuestFn<void*> RaceEventCtor(OFFSET);
+// and is still called exactly the same way (`RaceEventCtor()`). Likewise
+// InstallArmTrampolineHook's "returns a callable orig_X" pattern becomes
+// InstallTrampolineHook<Ret,Args...>(target, &Hook_X, "name"), still
+// returning something callable the same way.
+//
+// See ARM64_TRANSLATION_LAYER.md and guest_engine.h's own class comment for
+// the full design; this file is deliberately "just" marshaling glue.
+
+#include <cstdint>
+#include <type_traits>
+#include <utility>
+#include "guest_engine.h"
+
+// ---- Value marshaling ----
+// Pointer-shaped C++ types translate through G2H/H2G automatically.
+// Everything else (int, uint32_t, bool, enums, ...) passes through as a raw
+// 32-bit register value unchanged. This deliberately also covers this
+// codebase's existing "int, but actually holds an address" declarations
+// (e.g. GetCacheContextFn(int anyComponentPtr)) INCORRECTLY if left as
+// `int` - see the port notes in main.cpp/lan_event_injection.h for exactly
+// which declarations were changed from `int` to a real pointer type for
+// this reason, and which genuinely small integers (paintJobIndex, evType,
+// deltaMs, ...) were deliberately left as plain integer types.
+template<typename T, typename = void>
+struct GuestMarshal {
+    static uint32_t ToReg(T v) { return static_cast<uint32_t>(v); }
+    static T FromReg(uint32_t v) { return static_cast<T>(v); }
+};
+template<typename T>
+struct GuestMarshal<T, std::enable_if_t<std::is_pointer<T>::value>> {
+    static uint32_t ToReg(T v) {
+        return v ? GuestEngine::Instance().H2G(v) : 0;
+    }
+    static T FromReg(uint32_t v) {
+        return v ? reinterpret_cast<T>(GuestEngine::Instance().G2H(v)) : nullptr;
+    }
+};
+
+// Max args GuestFn/InstallTrampolineHook support - r0-r3 plus stack args,
+// generous headroom over anything this codebase's hooks or the JNI shim's
+// own trampolines actually need.
+constexpr size_t kMaxGuestFnArgs = 10;
+
+namespace guest_fn_detail {
+
+template<typename Ret, typename... Args, size_t... I>
+uint32_t InvokeAndPack(Ret (*fn)(Args...), const uint32_t regs[kMaxGuestFnArgs], std::index_sequence<I...>) {
+    if constexpr (std::is_void<Ret>::value) {
+        fn(GuestMarshal<Args>::FromReg(regs[I])...);
+        return 0;
+    } else {
+        Ret result = fn(GuestMarshal<Args>::FromReg(regs[I])...);
+        return GuestMarshal<Ret>::ToReg(result);
+    }
+}
+
+template<typename Ret, typename... Args>
+void DispatchCall(GuestEngine& eng, Ret (*fn)(Args...)) {
+    static_assert(sizeof...(Args) <= kMaxGuestFnArgs, "too many args for GuestFn/InstallTrampolineHook");
+    uint32_t r0 = 0, r1 = 0, r2 = 0, r3 = 0, sp = 0;
+    uc_reg_read(eng.uc(), UC_ARM_REG_R0, &r0);
+    uc_reg_read(eng.uc(), UC_ARM_REG_R1, &r1);
+    uc_reg_read(eng.uc(), UC_ARM_REG_R2, &r2);
+    uc_reg_read(eng.uc(), UC_ARM_REG_R3, &r3);
+    uc_reg_read(eng.uc(), UC_ARM_REG_SP, &sp);
+    uint32_t regs[kMaxGuestFnArgs];
+    for (size_t i = 0; i < sizeof...(Args); i++) {
+        regs[i] = eng.ReadIncomingArg((int)i, r0, r1, r2, r3, sp);
+    }
+    uint32_t result = InvokeAndPack(fn, regs, std::index_sequence_for<Args...>{});
+    uint32_t lr = 0;
+    uc_reg_read(eng.uc(), UC_ARM_REG_LR, &lr);
+    uc_reg_write(eng.uc(), UC_ARM_REG_R0, &result);
+    // Simulate "the hooked function ran and returned" - jump straight to
+    // the caller's LR. Unicorn switches ARM/Thumb decode based on bit0 of
+    // the PC value written, matching real AArch32 interworking.
+    uc_reg_write(eng.uc(), UC_ARM_REG_PC, &lr);
+}
+
+template<typename... Args>
+void PackArgs(uint32_t*, size_t) {}
+template<typename Head, typename... Tail>
+void PackArgs(uint32_t* regs, size_t i, Head h, Tail... tail) {
+    regs[i] = GuestMarshal<Head>::ToReg(h);
+    PackArgs(regs, i + 1, tail...);
+}
+
+} // namespace guest_fn_detail
+
+// A resolved, callable guest function - the "GetOutputNode/RaceEventCtor/
+// ..." replacement for a raw `(FnType)APP_ADDR(OFFSET)` cast.
+template<typename Ret, typename... Args>
+class GuestFn {
+public:
+    static_assert(sizeof...(Args) <= kMaxGuestFnArgs, "too many args for GuestFn");
+    GuestFn() = default;
+    explicit GuestFn(GuestAddr addr) : addr_(addr) {}
+    explicit operator bool() const { return addr_ != 0; }
+    GuestAddr addr() const { return addr_; }
+
+    Ret operator()(Args... args) const {
+        uint32_t regs[kMaxGuestFnArgs] = {0};
+        guest_fn_detail::PackArgs(regs, 0, args...);
+        uint32_t r0 = GuestEngine::Instance().CallGuestFunction(addr_, regs, (int)sizeof...(Args));
+        if constexpr (std::is_void<Ret>::value) {
+            (void)r0;
+        } else {
+            return GuestMarshal<Ret>::FromReg(r0);
+        }
+    }
+
+private:
+    GuestAddr addr_ = 0;
+};
+
+// Installs a trampoline hook exactly like this codebase's old
+// InstallArmTrampolineHook, but backed by GuestEngine - see this file's own
+// top comment and guest_engine.h's class comment for the mechanism. hookFn
+// must be a plain (non-capturing) function pointer, matching every existing
+// Hook_X function in this codebase already.
+template<typename Ret, typename... Args>
+GuestFn<Ret, Args...> InstallTrampolineHook(GuestAddr target, Ret (*hookFn)(Args...), const char* debugName) {
+    using FnPtr = Ret (*)(Args...);
+    auto* ctx = new FnPtr(hookFn); // leaked deliberately, see guest_engine.cpp's own note
+
+    auto dispatch = +[](GuestEngine& eng, void* userData) {
+        auto* fn = static_cast<FnPtr*>(userData);
+        guest_fn_detail::DispatchCall(eng, *fn);
+    };
+
+    GuestAddr tramp = GuestEngine::Instance().InstallTrampolineHookRaw(target, dispatch, ctx, debugName);
+    return GuestFn<Ret, Args...>(tramp);
+}

mpcore/src/main/cpp/emu/guest_heap.cpp

@@ -0,0 +1,237 @@
+#include "guest_heap.h"
+#include "../util/util.h"
+#include <atomic>
+#include <cstring>
+#include <time.h>
+
+// Temporary sanity check (2026-09-06) - confirm the new size-class free
+// list actually IS O(1) per call now, independent of whether it explains
+// the overall fread-rate mystery (first measurement showed it did NOT move
+// the needle - see ARM64_TRANSLATION_LAYER.md). Remove once confirmed.
+namespace {
+std::atomic<uint64_t> g_allocCalls2{0};
+uint64_t NowNs2() {
+    struct timespec ts;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    return (uint64_t)ts.tv_sec * 1000000000ull + ts.tv_nsec;
+}
+} // namespace
+
+void GuestHeap::Init(uint8_t* hostBase, GuestAddr arenaStart, uint32_t arenaSize) {
+    host_base_ = hostBase;
+    arena_start_ = arenaStart;
+    arena_end_ = arenaStart + arenaSize;
+    // Align the bump cursor so every payload (header is a multiple of kAlign
+    // by construction, see BlockHeader's own comment) comes back kAlign-aligned.
+    free_cursor_ = AlignUp(arenaStart, kAlign);
+    free_by_size_.clear();
+    live_bytes_ = peak_live_bytes_ = free_bytes_ = 0;
+    free_blocks_ = 0;
+}
+
+void GuestHeap::PushFree(GuestAddr dataAddr, uint32_t size) {
+    free_bytes_ += size;
+    free_blocks_++;
+    auto it = free_by_size_.find(size);
+    uint32_t next = (it == free_by_size_.end()) ? 0u : it->second;
+    memcpy(host_base_ + dataAddr, &next, 4);
+    if (it == free_by_size_.end()) {
+        free_by_size_.emplace(size, dataAddr);
+    } else {
+        it->second = dataAddr;
+    }
+}
+
+uint32_t GuestHeap::BlockSize(GuestAddr addr) const {
+    if (!IsValidLiveBlock(addr)) return 0;
+    // The USER size, not the footprint - callers (Shim_realloc) want to know
+    // how many bytes they were actually given, not how much the guard adds.
+    return HeaderAt(addr)->user_size;
+}
+
+void GuestHeap::WriteRedZone(GuestAddr dataAddr, uint32_t userSize) {
+    if (!kHeapDebugChecks) return;
+    std::memset(host_base_ + dataAddr + userSize, kRedZoneFill, kRedZoneBytes);
+}
+
+bool GuestHeap::CheckRedZone(GuestAddr dataAddr, uint32_t userSize) const {
+    if (!kHeapDebugChecks) return true;
+    const uint8_t* guard = host_base_ + dataAddr + userSize;
+    for (uint32_t i = 0; i < kRedZoneBytes; i++) {
+        if (guard[i] == kRedZoneFill) continue;
+        // Loud and specific: this identifies the block that was overflowed
+        // AND how far past its end the write reached, which is the whole
+        // point - the corruption is reported at the offending block rather
+        // than wherever it happens to surface later.
+        Log("GuestHeap: RED ZONE VIOLATION - block at 0x%x (user_size=%u) was written past its "
+            "end: guard byte %u of %u is 0x%02x, expected 0x%02x. Something overflowed THIS "
+            "block; see guest_heap.h's kHeapDebugChecks comment.",
+            dataAddr, userSize, i, kRedZoneBytes, guard[i], kRedZoneFill);
+        return false;
+    }
+    return true;
+}
+
+void GuestHeap::PoisonPayload(GuestAddr dataAddr, uint32_t userSize) {
+    if (!kHeapDebugChecks) return;
+    // Makes a use-after-free read obviously-wrong data. Matters more since
+    // Alloc stopped zeroing (2026-09-19): without this, a freed block keeps
+    // its old, plausible contents and a stale pointer keeps "working".
+    std::memset(host_base_ + dataAddr, kFreePoisonFill, userSize);
+}
+
+GuestAddr GuestHeap::Alloc(uint32_t size) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (!host_base_ || size == 0) return 0;
+    uint64_t callNo = g_allocCalls2.fetch_add(1, std::memory_order_relaxed) + 1;
+    uint64_t t0 = NowNs2();
+    const uint32_t userSize = AlignUp(size, kAlign);
+    // Everything below allocates in terms of the FOOTPRINT (user bytes plus
+    // the trailing guard). kRedZoneBytes is 0 unless checks are on, so this
+    // is identical to the previous arithmetic in normal builds.
+    const uint32_t payload = userSize + kRedZoneBytes;
+    auto logIfSampled = [&](const char* how) {
+        if (callNo <= 5 || callNo % 20000 == 0) {
+            Log("GuestHeap::Alloc: call #%llu (%s), took %lluns",
+                (unsigned long long)callNo, how, (unsigned long long)(NowNs2() - t0));
+        }
+    };
+    // Heap gauge (2026-09-19). Reads the member counters DIRECTLY rather
+    // than calling GetStats() - this function already holds mutex_, and
+    // GetStats takes it too, which on a non-recursive std::mutex would
+    // deadlock. Tied to allocation count rather than a timer so it reports
+    // during heavy loading and stays silent when the game is idle.
+    // "live" is what the guest actually holds right now; "carved" is how far
+    // the bump cursor has travelled, so carved-minus-live-minus-free is the
+    // fragmentation this allocator has not yet managed to give back.
+    if (callNo % 50000 == 0) {
+        constexpr double kMB = 1024.0 * 1024.0;
+        Log("GuestHeap: gauge @%lluk allocs - live=%.1fMB peak=%.1fMB free=%.1fMB "
+            "carved=%.1fMB of %.1fMB arena | freeBlocks=%u distinctSizes=%u",
+            (unsigned long long)(callNo / 1000), live_bytes_ / kMB, peak_live_bytes_ / kMB,
+            free_bytes_ / kMB,
+            ((free_cursor_ >= arena_start_) ? (free_cursor_ - arena_start_) : 0) / kMB,
+            ((arena_end_ >= arena_start_) ? (arena_end_ - arena_start_) : 0) / kMB,
+            free_blocks_, (unsigned)free_by_size_.size());
+    }
+
+    // Reuse: smallest free block that fits. O(log n) via the size-ordered
+    // map (an exact-size hit costs the same lookup) - deliberately not a
+    // linear scan over free blocks, see guest_heap.h's 2026-09-19 note and
+    // this allocator's own 2026-09-06 history with an O(n) scan.
+    auto it = free_by_size_.lower_bound(payload);
+    if (it != free_by_size_.end()) {
+        uint32_t blockSize = it->first;
+        GuestAddr blockAddr = it->second;
+        uint32_t next = 0;
+        memcpy(&next, host_base_ + blockAddr, 4);
+        if (next) {
+            it->second = next;
+        } else {
+            free_by_size_.erase(it);
+        }
+        free_bytes_ -= blockSize;
+        free_blocks_--;
+        BlockHeader* h = HeaderAt(blockAddr);
+        h->free = 0;
+        // Split the tail back into the free structure when what is left over
+        // can hold a header plus a minimally useful payload. Without this,
+        // exact sizing would just re-create stranding in a new shape (a 8MiB
+        // block permanently consumed by a 64KiB request).
+        uint32_t remainder = blockSize - payload;
+        if (remainder >= kMinSplitRemainder) {
+            h->size = payload;
+            GuestAddr tailHeader = blockAddr + payload;
+            BlockHeader* th = reinterpret_cast<BlockHeader*>(host_base_ + tailHeader);
+            th->magic = kMagic;
+            th->size = remainder - sizeof(BlockHeader);
+            th->free = 1;
+            th->user_size = th->size;
+            PushFree(tailHeader + sizeof(BlockHeader), th->size);
+        }
+        // The guard goes right after the USER bytes, so an overflow of even
+        // one byte past what the caller asked for is caught - even when the
+        // block reused was larger and did not get split.
+        h->user_size = userSize;
+        WriteRedZone(blockAddr, userSize);
+        live_bytes_ += h->size;
+        if (live_bytes_ > peak_live_bytes_) peak_live_bytes_ = live_bytes_;
+        logIfSampled("reuse");
+        return blockAddr;
+    }
+
+    // Nothing reusable - carve a fresh block at the EXACT requested size.
+    uint32_t needed = sizeof(BlockHeader) + payload;
+    if (free_cursor_ + needed > arena_end_) {
+        // Loud on purpose (2026-09-17): a silent `return 0` gets swallowed by
+        // downstream null-checks, and the real EA code does not check malloc.
+        Log("GuestHeap::Alloc: HEAP EXHAUSTED - payload=%u needed=%u but only %u bytes remain "
+            "(free_cursor_=0x%x arena_end_=0x%x) - returning 0 (null)",
+            payload, needed, (free_cursor_ <= arena_end_) ? (arena_end_ - free_cursor_) : 0,
+            free_cursor_, arena_end_);
+        return 0;
+    }
+    BlockHeader* h = reinterpret_cast<BlockHeader*>(host_base_ + free_cursor_);
+    h->magic = kMagic;
+    h->size = payload;
+    h->free = 0;
+    h->user_size = userSize;
+    GuestAddr dataAddr = free_cursor_ + sizeof(BlockHeader);
+    free_cursor_ += needed;
+    WriteRedZone(dataAddr, userSize);
+    live_bytes_ += payload;
+    if (live_bytes_ > peak_live_bytes_) peak_live_bytes_ = live_bytes_;
+    logIfSampled("bump-new");
+    return dataAddr;
+}
+
+bool GuestHeap::IsValidLiveBlock(GuestAddr addr) const {
+    if (!host_base_ || addr < arena_start_ + sizeof(BlockHeader) || addr >= free_cursor_) return false;
+    BlockHeader* h = HeaderAt(addr);
+    if (h->magic != kMagic) return false; // not a real header - wrong/stale address
+    if (h->free) return false;            // already free - reject double-free
+    // Payload must fit inside the arena and not run past the bump cursor -
+    // catches a header whose magic happens to match by coincidence but
+    // whose size field is nonsense (e.g. a wild write landed exactly 8
+    // bytes before some unrelated valid-looking magic value).
+    if (addr + h->size > free_cursor_) return false;
+    return true;
+}
+
+void GuestHeap::Free(GuestAddr addr) {
+    if (addr == 0) return; // free(NULL) is legal and common - silent, not a corruption signal
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (!IsValidLiveBlock(addr)) {
+        Log("GuestHeap::Free: rejected addr=0x%x - not a valid live block (wrong pointer, double-free, "
+            "or heap corruption - see guest_heap.h's own class comment)", addr);
+        return;
+    }
+    BlockHeader* h = HeaderAt(addr);
+    // Verify the guard BEFORE the block goes back on a free list: this is the
+    // last moment the overflow can still be attributed to this block rather
+    // than to whoever allocates the memory next. Deliberately not fatal - the
+    // point is a loud, precise report, and aborting here would make the
+    // engine less debuggable than the corruption it is reporting.
+    CheckRedZone(addr, h->user_size);
+    PoisonPayload(addr, h->user_size);
+    h->free = 1;
+    live_bytes_ -= h->size;
+    // Every block carries its exact payload size, so it goes straight onto
+    // the free list for that size - no class rounding, nothing excluded by
+    // being "too big" (the old scheme silently never reclaimed anything past
+    // its largest class). O(log n) for the map lookup.
+    PushFree(addr, h->size);
+}
+
+GuestHeap::Stats GuestHeap::GetStats() const {
+    std::lock_guard<std::mutex> lock(mutex_);
+    Stats s{};
+    s.liveBytes = live_bytes_;
+    s.peakLiveBytes = peak_live_bytes_;
+    s.freeBytes = free_bytes_;
+    s.carvedBytes = (free_cursor_ >= arena_start_) ? (free_cursor_ - arena_start_) : 0;
+    s.freeBlocks = free_blocks_;
+    s.distinctFreeSizes = (uint32_t)free_by_size_.size();
+    s.arenaBytes = (arena_end_ >= arena_start_) ? (arena_end_ - arena_start_) : 0;
+    return s;
+}

mpcore/src/main/cpp/emu/guest_heap.h

@@ -0,0 +1,249 @@
+#pragma once
+
+#include "guest_types.h"
+#include <map>
+#include <mutex>
+
+// Minimal first-fit heap allocator carved out of a fixed-size arena that
+// lives INSIDE the same flat guest/host region as the loaded libapp.so
+// image (see GuestEngine). Backs the malloc/free/calloc import shims, so
+// that any object the guest code allocates at runtime (e.g. InjectSyntheticEvent's
+// RaceEvent/CashReward/FakeActor - see lan_event_injection.h) gets a real
+// guest address in the SAME identity-offset numbering as every static
+// OFFSET macro in this codebase, not an arbitrary host heap pointer outside
+// the mapped region.
+//
+// 2026-09-06: replaced the original first-fit-scan-the-whole-arena design
+// with a size-class-segregated free list, after directly measuring the old
+// one as the real (confirmed, quantified) root cause of the OBB-index-build
+// performance cliff investigated in ARM64_TRANSLATION_LAYER.md - the old
+// Alloc() scanned every block ever carved, free or in-use, on every call,
+// so cost grew with total historical allocation count (measured: 0 blocks
+// scanned at call #1, 9294 at call #40000, ~30us/call once the arena's
+// free/used population reached its steady-state size). Requested sizes are
+// now rounded up to one of a small set of power-of-two size classes
+// (kAlign=8 .. kMaxSizeClassBytes, see kNumSizeClasses's own comment for
+// its current ceiling); each class keeps its own singly-linked free list
+// (the "next" pointer for a free block lives in the block's own now-unused
+// payload - always at least kAlign=8 bytes, enough for one 32-bit guest
+// address), making both Alloc() and Free() O(1) instead of O(n). Only a
+// request bigger than the largest class - now a genuinely rare, near-
+// arena-sized edge case rather than the routine "anything over 64KiB" path
+// it used to be (see kNumSizeClasses's own 2026-09-18 comment) - still
+// bump-allocates fresh and is simply never reused on free.
+//
+// This heap backs BOTH the guest program's own malloc/free/calloc/realloc
+// AND short-lived JNI marshaling buffers (see import_shims.cpp/jni_shim.cpp)
+// - i.e. arbitrary, uncontrolled usage from millions of lines of real ARM32
+// game code sharing one arena. A single wrong free() anywhere in that code
+// (or a buffer overflow into a neighboring block) can otherwise silently
+// corrupt any other live allocation - confirmed live this session, tracked
+// down to the permanently-cached guest JNIEnv structure getting overwritten
+// this way. Two structural responses: (1) permanent, safety-critical
+// structures (guest JNIEnv/JavaVM) no longer live in this heap at all - see
+// GuestEngine::AllocPermanent's own comment; (2) this heap now validates a
+// magic value on every Free() so a wrong/stale address is rejected and
+// logged instead of silently corrupting whatever bytes precede it. Doesn't
+// stop a wild WRITE (nothing but a full guard-page/MMU scheme would), but
+// catches the specific failure mode actually observed: a bad free().
+class GuestHeap {
+public:
+    // hostBase: host pointer corresponding to guest address 0 (i.e. the
+    // engine's G2H(0)). arenaStart/arenaSize: guest-address range this heap
+    // is allowed to hand out (must not overlap the loaded image or the
+    // guest stack).
+    void Init(uint8_t* hostBase, GuestAddr arenaStart, uint32_t arenaSize);
+
+    // Returns 0 (a guest NULL) on failure, matching malloc's own contract.
+    // Thread-safe (mutex-guarded) - now that real guest threads exist (see
+    // emu/pthread_shim.h), any of them can call malloc/free concurrently.
+    //
+    // Does NOT zero the returned memory (2026-09-19). malloc makes no such
+    // promise; only calloc does, and Shim_calloc now zeroes explicitly. The
+    // previous behaviour zeroed the whole rounded-up class block on every
+    // single allocation - for an 8MiB class that was an 8MiB memset per call,
+    // and it forced physical commit of pages the guest might never touch.
+    GuestAddr Alloc(uint32_t size);
+    // No-ops (logged) if `addr` doesn't point at a real, currently-allocated
+    // block's payload - see class comment.
+    void Free(GuestAddr addr);
+    // Exact payload size of a live block, or 0 if `addr` isn't one. Lets
+    // Shim_realloc copy min(oldSize,newSize) instead of guessing (it used to
+    // copy the NEW size out of a possibly-smaller old block).
+    uint32_t BlockSize(GuestAddr addr) const;
+
+    struct Stats {
+        uint64_t liveBytes;     // payload currently handed out to the guest
+        uint64_t peakLiveBytes; // high-water mark of the above
+        uint64_t freeBytes;     // payload sitting in the free structure, reusable
+        uint64_t carvedBytes;   // bump cursor travel - memory this arena has ever touched
+        uint32_t freeBlocks;
+        uint32_t distinctFreeSizes;
+        uint32_t arenaBytes;
+    };
+    // Cheap: every field is a counter maintained in O(1) by Alloc/Free, not
+    // computed by walking anything.
+    Stats GetStats() const;
+
+private:
+    // 16 bytes, not 12: with a 12-byte header the bump cursor advanced by
+    // 12+payload, so payload alignment alternated between 8- and 4-byte and
+    // could hand a 4-aligned buffer to guest code doing 8-byte accesses.
+    // Padding to 16 keeps every payload 8-aligned (arena start is aligned and
+    // payloads are multiples of kAlign), and makes the split arithmetic below
+    // exact. Costs 4 bytes per block, trivial next to the ~4x this file's
+    // 2026-09-19 rework removes.
+    // ---- memory-error detection (2026-09-19, task #45) ----
+    // OFF by default. The existing magic check on Free catches a wrong or
+    // stale POINTER, but not the more insidious failure this layer is prone
+    // to: a shim writing a few bytes past the end of a block and silently
+    // corrupting whatever live object follows. That has already happened
+    // once in this project's history (the guest JNIEnv structure was
+    // overwritten that way - see this class's own comment) and it surfaces
+    // subsystems later, looking like an unrelated crash.
+    //
+    // With checks on, each block gets a trailing guard filled with a known
+    // pattern, verified when the block is freed, and freed payloads are
+    // poisoned so a use-after-free reads obviously-wrong data instead of
+    // plausible stale values. The latter matters more since 2026-09-19,
+    // when Alloc stopped zeroing.
+    //
+    // Both cost memory and time, so this follows the same opt-in discipline
+    // as every other diagnostic here (see kTraceHeapAllocations in
+    // import_shims.cpp): flip to true while hunting a corruption bug, never
+    // leave it on. With it false, kRedZoneBytes is 0 and every guard-related
+    // branch folds away at compile time.
+    static constexpr bool kHeapDebugChecks = false;
+    static constexpr uint32_t kRedZoneBytes = kHeapDebugChecks ? 16 : 0;
+    static constexpr uint8_t kRedZoneFill = 0xBE;  // "guard"
+    static constexpr uint8_t kFreePoisonFill = 0xDF; // "dead free"
+
+    struct BlockHeader {
+        uint32_t magic; // kMagic if this is a real header GuestHeap itself wrote - see class comment
+        // Total payload footprint this block occupies, INCLUDING the trailing
+        // guard when checks are on. Free lists, splitting and IsValidLiveBlock
+        // all work in these terms.
+        uint32_t size;
+        uint32_t free;  // 1 = free, 0 = in use
+        // What the caller actually asked for (aligned up) - i.e. size minus
+        // the guard. Was pure alignment padding before; it is maintained
+        // unconditionally so BlockSize() can report the user-visible size and
+        // realloc can copy the right amount, whether or not checks are on.
+        uint32_t user_size;
+    };
+    static constexpr uint32_t kMagic = 0x47484B21; // "GuestHeap blocK!" - arbitrary but distinctive
+    static constexpr uint32_t kAlign = 8;
+    static uint32_t AlignUp(uint32_t v, uint32_t a) { return (v + a - 1) & ~(a - 1); }
+
+    // 2026-09-19 REWORK - exact sizing, measured against real hardware.
+    // The size-class scheme described above (kept in the history below
+    // because its own reasoning was sound for the bug it fixed) rounded
+    // EVERY request up to the next power of two and bump-allocated the full
+    // class size. Measured cost on the Galaxy A9 running the real ARM32
+    // build of this same game: native heap ~46MB in menus, ~199MB with a
+    // race loaded - while this engine exhausted a 768MB arena before the
+    // prologue even finished. That ~4x gap decomposes exactly as the scheme
+    // predicts: ~1.5x average waste from rounding (a 4.1MB request took
+    // 8MB, a 70KB request took 128KB) multiplied by the stranding caused by
+    // segregated per-class free lists, where a freed 8MB block could never
+    // satisfy a 64KB request no matter how much of the arena it held.
+    //
+    // Replaced by exact-size allocation with a single size-ordered free
+    // structure. Deliberately NOT a linear best-fit scan: this allocator's
+    // own history (the 2026-09-06 note above) is that an O(n) scan per
+    // allocation was itself a measured performance cliff, so reuse is a
+    // std::map lookup - lower_bound for "smallest free block that fits",
+    // O(log n), with the same cost for an exact hit. Blocks of identical
+    // size share one intrusive singly-linked list (the "next" pointer lives
+    // in the free block's own payload, always >= kAlign bytes), so the map
+    // holds one node per DISTINCT live free size, not per free block.
+    //
+    // A block larger than the request is split and the remainder returned to
+    // the free structure, which is what keeps exact sizing from simply
+    // re-creating stranding in a different shape. Still no coalescing of
+    // adjacent free blocks - consistent with this allocator's long-standing
+    // choice, and the same reasoning still applies: reuse alone is what
+    // converts "grows forever" into "reaches a steady state".
+    static constexpr uint32_t kMinSplitRemainder = sizeof(BlockHeader) + kAlign;
+
+    // ---- history: the superseded size-class scheme ----
+    // Size classes: kAlign(8), 16, 32, ... up to kAlign << (kNumSizeClasses-1).
+    // 27 classes tops out at 8 << 26 = 512MiB.
+    //
+    // 2026-09-18 (ARM64_TRANSLATION_LAYER.md - the sub_4BA588/"loadNodeUncached"
+    // chase, ROOT CAUSE): widened from 14 classes (64KiB ceiling) to 27
+    // (512MiB ceiling) - the >64KiB "oversized" path used to bump-allocate
+    // fresh on every call and NEVER reuse freed memory (see the old
+    // GuestHeap::Alloc's own now-removed comment), which was root-caused
+    // live on the Pixel 6a as the single cause of BOTH the "onCreate never
+    // completes" heap-exhaustion crash AND a separate, later-discovered
+    // crash in sub_4BA588 ("loadNodeUncached"): a real ~175KB M3G resource
+    // buffer allocation failed because the 256MB arena was already full of
+    // permanently-stranded freed-but-unreclaimed oversized blocks from
+    // earlier in the same session, the real EA code doesn't check malloc's
+    // result for null (reasonably, since real hardware's own heap
+    // essentially never fails a request this size), and the null flows
+    // downstream into a reader that legitimately-but-incorrectly reports
+    // "0 bytes available" forever. Real hardware never hits this because
+    // its heap never actually runs out. Simplest complete fix: there is no
+    // structural difference between a "small" and a "large" allocation from
+    // this allocator's own point of view - the SAME O(1) size-classed
+    // free-list scheme that already correctly reuses freed <=64KiB blocks
+    // (see the 2026-09-06 comment two paragraphs up) works identically at
+    // any size, so widening it removes the separate never-reclaimed path
+    // entirely rather than adding a second, differently-shaped one next to
+    // it. Trades up to ~2x internal fragmentation per oversized object
+    // (worst case: a request just over a class boundary rounds up to
+    // double) for a hard bound on total arena growth - a real win given the
+    // failure mode being fixed is fully UNBOUNDED growth, not excess
+    // fragmentation. Does not coalesce adjacent free blocks (consistent
+    // with this allocator's existing choice not to do so even for small
+    // blocks - see the class comment) - not needed for this fix: reuse
+    // alone converts "grows forever" into "reaches a steady state," which
+    // is the actual guarantee being restored here.
+    // (kNumSizeClasses/SizeClassFor/SizeClassBytes removed 2026-09-19 with
+    // the scheme they implemented - see the rework note above.)
+
+    // Pushes a free block onto the intrusive list for its exact size.
+    void PushFree(GuestAddr dataAddr, uint32_t size);
+
+    // Guard handling - all no-ops when kHeapDebugChecks is false.
+    // `dataAddr` is a payload address, `userSize` what the caller asked for;
+    // the guard lives immediately after the user payload so that a one-byte
+    // overflow is caught, rather than at the very end of a possibly-larger
+    // block where slack would hide it.
+    void WriteRedZone(GuestAddr dataAddr, uint32_t userSize);
+    // Logs and returns false if the guard was damaged.
+    bool CheckRedZone(GuestAddr dataAddr, uint32_t userSize) const;
+    void PoisonPayload(GuestAddr dataAddr, uint32_t userSize);
+
+    BlockHeader* HeaderAt(GuestAddr addr) const {
+        return reinterpret_cast<BlockHeader*>(host_base_ + addr - sizeof(BlockHeader));
+    }
+    GuestAddr AddrOfHeader(BlockHeader* h) const {
+        return static_cast<GuestAddr>(reinterpret_cast<uint8_t*>(h) - host_base_);
+    }
+    // True if `addr` is in-range AND the bytes immediately before it look
+    // like a real header this allocator wrote (magic matches) AND that
+    // block is currently marked in-use (double-free protection too).
+    bool IsValidLiveBlock(GuestAddr addr) const;
+
+    uint8_t* host_base_ = nullptr;
+    GuestAddr arena_start_ = 0;
+    GuestAddr arena_end_ = 0;   // one-past-the-end of the arena
+    GuestAddr free_cursor_ = 0; // next never-yet-used byte (bump pointer for the "no free block fits" case)
+    // exact payload size -> head of that size's intrusive free list (a
+    // block's data address). One map node per DISTINCT free size, not per
+    // free block - see the 2026-09-19 rework note above.
+    std::map<uint32_t, GuestAddr> free_by_size_;
+    // Accounting for GetStats (2026-09-19). Maintained incrementally so the
+    // gauge costs nothing to read - the point of it is to answer "how much
+    // does this game actually need" with a measured number instead of
+    // inferring it from the process's resident set, which mixes in thread
+    // stacks and never shrinks once a page has been touched.
+    uint64_t live_bytes_ = 0;
+    uint64_t peak_live_bytes_ = 0;
+    uint64_t free_bytes_ = 0;
+    uint32_t free_blocks_ = 0;
+    mutable std::mutex mutex_;
+};

mpcore/src/main/cpp/emu/guest_trace.cpp

@@ -0,0 +1,131 @@
+#include "guest_trace.h"
+
+#include <atomic>
+#include <chrono>
+#include <cstdio>
+#include <cstring>
+#include <mutex>
+#include <thread>
+#include <time.h>
+#include <unistd.h>
+
+namespace {
+
+std::atomic<bool> g_enabled{false};
+
+uint64_t NowMs() {
+    struct timespec ts;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    return (uint64_t)ts.tv_sec * 1000 + (uint64_t)ts.tv_nsec / 1000000;
+}
+
+uint64_t g_epochMs = 0;
+std::once_flag g_epochOnce;
+
+// Block-trace ring: raw array + atomic write index, same accepted-torn-read
+// tradeoff as guest_engine.cpp's own g_liveTraceRing (a diagnostic, not a
+// correctness-critical path) - deliberately NOT a mutex-guarded structure,
+// since this callback fires once per translated basic block and any lock
+// there would dominate the very execution speed this trace exists to
+// measure. 4M entries * 12 bytes = 48MB, comfortably bounded.
+struct BlockEntry {
+    uint32_t relMs;
+    uint32_t tid;
+    uint32_t addr;
+};
+constexpr size_t kRingSize = 4 * 1024 * 1024;
+BlockEntry g_ring[kRingSize];
+std::atomic<uint64_t> g_pos{0};
+
+constexpr char kGuestTracePath[] = "/data/data/com.ea.games.nfs13_arm/files/guest_trace.log";
+constexpr char kJniTracePath[] = "/data/data/com.ea.games.nfs13_arm/files/jni_trace.log";
+
+} // namespace
+
+uint64_t GuestTraceEpochMs() {
+    std::call_once(g_epochOnce, [] { g_epochMs = NowMs(); });
+    return g_epochMs;
+}
+
+void EnableFullGuestTrace() {
+    GuestTraceEpochMs(); // establish the shared epoch at the moment tracing is armed
+    g_enabled.store(true, std::memory_order_relaxed);
+}
+
+bool FullGuestTraceEnabled() {
+    return g_enabled.load(std::memory_order_relaxed);
+}
+
+void FullGuestTraceHookCb(uc_engine*, uint64_t address, uint32_t, void*) {
+    uint64_t idx = g_pos.fetch_add(1, std::memory_order_relaxed);
+    BlockEntry& e = g_ring[idx % kRingSize];
+    e.relMs = (uint32_t)(NowMs() - GuestTraceEpochMs());
+    e.tid = (uint32_t)gettid();
+    e.addr = (uint32_t)address;
+}
+
+void StartGuestTraceDumpThread() {
+    static std::atomic<bool> started{false};
+    bool expected = false;
+    if (!started.compare_exchange_strong(expected, true)) return; // already running
+
+    std::thread([]() {
+        FILE* f = nullptr;
+        uint64_t lastDumped = 0;
+        while (true) {
+            std::this_thread::sleep_for(std::chrono::seconds(2));
+            if (!FullGuestTraceEnabled()) continue;
+            if (!f) {
+                f = fopen(kGuestTracePath, "a");
+                if (!f) continue;
+                fprintf(f, "---- guest_trace opened, epoch_ms(monotonic)=%llu ----\n",
+                        (unsigned long long)GuestTraceEpochMs());
+                fflush(f);
+            }
+            uint64_t posNow = g_pos.load(std::memory_order_relaxed);
+            if (posNow <= lastDumped) continue;
+            uint64_t start = lastDumped;
+            if (posNow - lastDumped > kRingSize) {
+                // Consumer fell behind the writer by more than a full ring -
+                // say so explicitly rather than silently presenting a gap as
+                // a continuous sequence (matches caveman_retrieve's own
+                // "non-adjacent" marker convention for the same reason).
+                fprintf(f, "---- [guest_trace: %llu entries dropped, ring overflowed] ----\n",
+                        (unsigned long long)(posNow - lastDumped - kRingSize));
+                start = posNow - kRingSize;
+            }
+            for (uint64_t i = start; i < posNow; i++) {
+                const BlockEntry& e = g_ring[i % kRingSize];
+                fprintf(f, "[%u] [tid=%u] 0x%x\n", e.relMs, e.tid, e.addr);
+            }
+            fflush(f);
+            lastDumped = posNow;
+        }
+    }).detach();
+}
+
+void LogJniCall(const char* fmt, ...) {
+    if (!FullGuestTraceEnabled()) return;
+
+    char buf[512];
+    va_list ap;
+    va_start(ap, fmt);
+    vsnprintf(buf, sizeof(buf), fmt, ap);
+    va_end(ap);
+
+    static std::mutex m;
+    static FILE* f = nullptr;
+    std::lock_guard<std::mutex> lock(m);
+    if (!f) {
+        f = fopen(kJniTracePath, "a");
+        if (f) {
+            fprintf(f, "---- jni_trace opened, epoch_ms(monotonic)=%llu ----\n",
+                    (unsigned long long)GuestTraceEpochMs());
+        }
+    }
+    if (f) {
+        fprintf(f, "[%llu] [tid=%d] %s\n",
+                (unsigned long long)(NowMs() - GuestTraceEpochMs()), gettid(), buf);
+        fflush(f);
+    }
+}

mpcore/src/main/cpp/emu/guest_trace.h

@@ -0,0 +1,55 @@
+#pragma once
+
+#include <unicorn/unicorn.h>
+#include <cstdint>
+#include <cstdarg>
+
+// Full, file-backed execution trace for the emulated engine - correlates
+// against the Galaxy A9's own `trace_agent` full-call trace (built the same
+// day, see ARM64_TRANSLATION_LAYER.md's 2026-09-06 entries) using a shared
+// monotonic-clock epoch, for the "where does the emulated engine's real
+// execution first diverge from real hardware's" investigation - both
+// devices confirmed to take the same useAssetsFileSystem()/OBB-gated path,
+// yet only one renders, so the divergence must be found downstream of that,
+// not assumed from a single-variable theory.
+//
+// Two files, deliberately not interleaved into one (still directly
+// comparable by timestamp):
+//   - guest_trace.log: one line per executed basic block (UC_HOOK_BLOCK -
+//     the same cheap, already-proven mechanism as profiler.h's own sampling
+//     hook and guest_engine.cpp's existing TraceRing/LiveTraceRing). This is
+//     BLOCK-level, not strictly call-level: reconstructing an accurate
+//     guest call sequence from it means keeping only addresses that are
+//     real function entry points, cross-referenced against the IDA
+//     database offline - classifying that live, per block, would need a
+//     disassembler in the hot path, which this project has deliberately
+//     avoided everywhere else for cost reasons.
+//   - jni_trace.log (written by jni_shim.cpp via LogJniCall): one line per
+//     real Java-side JNI call the guest makes (Call*Method family via
+//     InvokeCall, Get/Set*Field via DoGetField/DoSetField, GetMethodID/
+//     GetFieldID lookups, RegisterNatives) - the same call granularity as
+//     the A9 tracer's own JNI table patch, so the two are diffable line by
+//     line once resolved to real names.
+void EnableFullGuestTrace();
+bool FullGuestTraceEnabled();
+
+// UC_HOOK_BLOCK callback - pass directly to uc_hook_add, gated on
+// FullGuestTraceEnabled() by the caller (see guest_engine.cpp).
+void FullGuestTraceHookCb(uc_engine* uc, uint64_t address, uint32_t size, void* user_data);
+
+// Starts (once) a background thread that appends newly-recorded block-trace
+// entries to guest_trace.log every 2 seconds until the process exits. No-op
+// (just sleeps) while FullGuestTraceEnabled() is false.
+void StartGuestTraceDumpThread();
+
+// Monotonic-clock epoch (ms since CLOCK_MONOTONIC's own reference point),
+// established the moment EnableFullGuestTrace() is first called. Both
+// guest_trace.log and jni_trace.log timestamp every line as an offset from
+// this same epoch, so the two files line up directly - no wall-clock/RTC
+// involved, matching this project's existing NowMs()-style conventions.
+uint64_t GuestTraceEpochMs();
+
+// Shared JNI-call logger (used by jni_shim.cpp) - appends a timestamped,
+// tid-tagged line to jni_trace.log. No-op while FullGuestTraceEnabled() is
+// false, so ordinary runs pay no cost beyond the one atomic flag check.
+void LogJniCall(const char* fmt, ...);

mpcore/src/main/cpp/emu/guest_types.h

@@ -0,0 +1,39 @@
+#pragma once
+
+// Shared basic types for the ARM32-on-ARM64 in-process translation core.
+// See /ARM64_TRANSLATION_LAYER.md for the design this implements.
+
+#include <cstdint>
+
+// A guest address is "offset from the loaded libapp.so image's own base"
+// (vaddr 0, since the ELF is ET_DYN with a preferred base of 0 - confirmed
+// via readelf/pyelftools this session). This is DELIBERATELY the exact same
+// number space every existing OFFSET macro in this codebase already uses
+// (ARCHITECTURE.md's own "IDA addresses == file offsets == APP_ADDR
+// argument" observation) - the whole point of choosing this layout is that
+// none of the ~150 hand-derived offsets in lan_event_injection.h etc. need
+// to change.
+using GuestAddr = uint32_t;
+
+// bit0 of a GuestAddr, when passed to CallGuestFunction/InstallCodeHook,
+// selects Thumb vs ARM instruction decoding - same convention this
+// project's own armhook.cpp (isThumbMode/makeThumbPtr) already used for a
+// real (non-emulated) process. Every hook site in this codebase so far
+// targets ARM-mode code (confirmed via IDA disasm before hooking each one),
+// so bit0 is 0 everywhere in practice today, but the mechanism supports
+// Thumb targets too.
+constexpr GuestAddr kThumbBit = 1;
+
+enum class HookMode {
+    // Callback runs, then guest execution CONTINUES from the original
+    // instruction (nothing skipped) - used to observe/modify state without
+    // altering control flow, or as the entry point for a "modify args, then
+    // fall through to real code" hook (matches this project's existing
+    // "wrap" hooks, e.g. Hook_BuildTrackScenePath).
+    kWrap,
+    // Callback fully replaces the target: after it returns, execution jumps
+    // straight to the guest LR (as if the target function returned) without
+    // ever running the target's own instructions (matches e.g.
+    // Hook_CopSoundsTick's "skip the body entirely" pattern).
+    kReplace,
+};

mpcore/src/main/cpp/emu/import_shims.cpp

@@ -0,0 +1,529 @@
+#include "import_shims.h"
+#include "jni_shim.h"
+#include "../util/util.h"
+#include <cstring>
+#include <cctype>
+#include <cstdlib>
+#include <math.h>
+#include <ctime>
+#include <string>
+#include <mutex>
+#include <atomic>
+#include <android/log.h>
+
+// ---- Known, documented gaps in this shim layer (prototype scope) ----
+// - Corrected (2026-08-29): `armeabi-v7a` uses the **softfp** calling
+//   convention (confirmed - this is the standard, documented Android NDK
+//   choice for this ABI, kept for compatibility with older soft-float
+//   armeabi code even though the CPU has real VFP hardware) - float/double
+//   args and return values pass through r0-r3 (and the stack) as raw bit
+//   patterns, NOT through S/D VFP registers. So float marshaling via
+//   `memcpy` on the raw uint32_t register value (see GetFloatField in
+//   jni_shim.cpp, and every GLfloat parameter in gles_shim.cpp) is already
+//   CORRECT, not a gap - the earlier version of this comment overstated the
+//   risk. Only real jlong/jdouble (8-byte, register-pair-aligned) values
+//   remain genuinely unhandled (see MarshalArgs*'s own comment in
+//   jni_shim.cpp), which is a JNI/varargs marshaling limitation, not a
+//   float-ABI one.
+// - __cxa_guard_acquire/release below are still NOT thread-safe (no atomic
+//   CAS, no futex wait for a concurrent initializer) - a real race here
+//   (two guest threads racing the same function-local static's first-time
+//   init) would need actual fixing, not just documenting, but hasn't been
+//   observed yet. Real pthread_create/join/mutex/cond support now lives in
+//   emu/pthread_shim.h/.cpp (added once the prototype actually needed guest
+//   threads to stop the engine deadlocking on its own worker threads - see
+//   ARM64_TRANSLATION_LAYER.md). The pthread_key_*/TLS shims below now use
+//   a `thread_local` value array (fixed at this same session) - only key
+//   ALLOCATION (pthread_key_create's counter) is still process-wide/shared,
+//   matching real bionic's own TLS-key semantics.
+// - __cxa_atexit is a no-op (guest static destructors never run) - harmless
+//   for a process that's never expected to cleanly "exit" its guest image.
+// - dladdr/__dynamic_cast/getauxval/qsort/longjmp/the *printf family are
+//   NOT implemented (still trap to the generic "unresolved, return 0"
+//   handler) - each needs either real variadic-argument marshaling
+//   (printf/snprintf/__android_log_print), a guest-callback trampoline
+//   (qsort's comparator), or non-trivial semantics (longjmp) this pass
+//   deliberately didn't attempt. File I/O (fopen/fread/fclose/...) is in
+//   the same "deliberately not attempted" bucket - would need a guest
+//   FILE* handle table, same shape as JniHandleTable, not built yet.
+// Every gap above was a deliberate scope cut for this session, not an
+// oversight - see ARM64_TRANSLATION_LAYER.md's own "open risks" section for
+// the class of work this belongs to.
+
+namespace {
+
+uint32_t Shim_aeabi_memcpy(GuestEngine& eng, uint32_t dest, uint32_t src, uint32_t n, uint32_t, uint32_t) {
+    if (dest && src && n) memcpy(eng.G2H(dest), eng.G2H(src), n);
+    return dest;
+}
+uint32_t Shim_aeabi_memmove(GuestEngine& eng, uint32_t dest, uint32_t src, uint32_t n, uint32_t, uint32_t) {
+    if (dest && src && n) memmove(eng.G2H(dest), eng.G2H(src), n);
+    return dest;
+}
+// AEABI memset/memclr use (dest, n, c) - deliberately reversed vs libc
+// memset(dest, c, n). See ARM IHI 0043 (AEABI) sec 7.2.
+uint32_t Shim_aeabi_memset(GuestEngine& eng, uint32_t dest, uint32_t n, uint32_t c, uint32_t, uint32_t) {
+    if (dest && n) memset(eng.G2H(dest), (int)c, n);
+    return dest;
+}
+// __memcpy_chk (2026-09-16, ARM64_TRANSLATION_LAYER.md - the "isolated
+// std::ostringstream repro" test): bionic's _FORTIFY_SOURCE=2 wrapper around
+// memcpy, emitted by clang whenever the compiler can prove a destination
+// object's size at compile time - unlike __aeabi_memcpy* above, this is a
+// LIBC symbol, not an AEABI one, so a freshly-built c++_static artifact
+// linking straight against bionic (rather than going through libapp.so's
+// own already-compiled, already-relocated calls) can reference it even
+// though nothing in this codebase had needed it before. Confirmed live:
+// missing this shim silently turned every one of ostream_repro.so's own
+// `memcpy(outBuf, ...)` calls into a no-op (the generic "unresolved import,
+// return 0" fallback doesn't copy anything), which looked EXACTLY like a
+// real ostringstream-extraction bug (result buffer stayed all-zero) until
+// this was traced back to the missing shim - a confound worth documenting
+// so it doesn't get mistaken for engine-level memory corruption again.
+// destlen is bionic's real 4th argument (the compiler-computed destination
+// object size); this shim logs instead of aborting if n exceeds it (real
+// bionic would abort() - a hard crash - which is almost certainly less
+// useful for debugging a guest than a loud log line here).
+uint32_t Shim_memcpy_chk(GuestEngine& eng, uint32_t dest, uint32_t src, uint32_t n, uint32_t destlen, uint32_t) {
+    if (destlen != 0xFFFFFFFFu && n > destlen) {
+        Log("GuestEngine: __memcpy_chk: n(%u) > destlen(%u) at dest=0x%x, src=0x%x - real bionic "
+            "would abort() here; copying anyway (see import_shims.cpp)", n, destlen, dest, src);
+    }
+    if (dest && src && n) memcpy(eng.G2H(dest), eng.G2H(src), n);
+    return dest;
+}
+// ---- Minimal bionic locale-family shims (2026-09-16, same investigation)
+// ----
+// A statically-linked libc++abi's classic/"C" locale singleton calls these
+// real bionic entry points during its own one-time setup - none had ever
+// been needed before this session (every previous locale-touching call
+// site in this codebase went through rtti_shims.cpp's own hand-written
+// _ZNSt6__ndk1*-prefixed libc++-internal shims instead, which never call
+// down into bionic's OWN locale layer at all - see rtti_shims.cpp's top
+// comment). newlocale returning 0 (this engine's default "unresolved,
+// return 0" behavior) was tested live and did NOT block basic char-only
+// ostringstream writes from working (this session's own repro test's
+// reported length came back correct even before this shim was added), but
+// leaving it unresolved is still a real, avoidable confound for any FUTURE
+// artifact that touches actual locale-sensitive formatting - a minimal,
+// always-succeeds "C locale" stand-in costs nothing and removes the
+// ambiguity. Genuinely locale-SENSITIVE behavior (real multi-locale
+// support) is out of scope, same as rtti_shims.cpp's own use_facet gap -
+// this only needs to make single-locale ("C"/classic) code paths not
+// silently fail.
+GuestAddr g_fakeLocaleT = 0; // lazily allocated on first newlocale() call
+uint32_t Shim_newlocale(GuestEngine& eng, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) {
+    if (!g_fakeLocaleT) g_fakeLocaleT = eng.AllocPermanent(4); // never freed - see AllocPermanent's own comment
+    return g_fakeLocaleT ? g_fakeLocaleT : 1u; // never return a real 0/NULL "failed" locale_t
+}
+uint32_t Shim_uselocale(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) {
+    return g_fakeLocaleT ? g_fakeLocaleT : 1u; // "previous locale" - same single fake handle either way
+}
+uint32_t Shim_freelocale(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) {
+    return 0; // never actually freed - g_fakeLocaleT is a permanent singleton, matches AllocPermanent's own contract
+}
+uint32_t Shim_aeabi_memclr(GuestEngine& eng, uint32_t dest, uint32_t n, uint32_t, uint32_t, uint32_t) {
+    if (dest && n) memset(eng.G2H(dest), 0, n);
+    return dest;
+}
+
+// Diagnostic (2026-09-17, ARM64_TRANSLATION_LAYER.md - the 0x3d3d3d3d
+// use-after-free-shaped chase): per-allocation malloc/free tracing with the
+// caller's guest LR, to reconstruct which call sites touch a given address
+// across its lifetime.
+//
+// OFF by default since 2026-09-19. That investigation is closed, and this
+// pair turned out to be by far the loudest thing in the engine: a single
+// prologue-load capture held 554,383 malloc lines and 539,003 free lines -
+// 93% of a 1.38-million-line log once __aeabi_memcpy's probe is counted in.
+// That volume does not burn CPU so much as block the app against logd, which
+// is exactly the "loading takes forever but the phone isn't even warm"
+// symptom the user reported. Same opt-in discipline as the UC_HOOK_BLOCK
+// diagnostics (see guest_engine.cpp) - flip to true only for a short,
+// targeted capture, never leave it on.
+constexpr bool kTraceHeapAllocations = false;
+
+uint32_t Shim_malloc(GuestEngine& eng, uint32_t size, uint32_t, uint32_t, uint32_t, uint32_t) {
+    GuestAddr addr = eng.heap().Alloc(size);
+    // Small allocations only (<=256 bytes - covers both the tiny
+    // attribute-map bucket array and the ~33-byte shader-header string
+    // buffer implicated in that investigation).
+    if (kTraceHeapAllocations && size <= 256) {
+        uint32_t callerLr = 0;
+        if (uc_engine* uc = eng.uc()) uc_reg_read(uc, UC_ARM_REG_LR, &callerLr);
+        Log("GuestHeap: malloc(size=%u) -> 0x%x from guest LR=0x%x", size, addr, callerLr);
+    }
+    return addr;
+}
+uint32_t Shim_free(GuestEngine& eng, uint32_t ptr, uint32_t, uint32_t, uint32_t, uint32_t) {
+    // No size available here without reading GuestHeap's own private header,
+    // so this logs every free() - fine for a bounded capture, ruinous left on.
+    if (kTraceHeapAllocations) {
+        uint32_t callerLr = 0;
+        if (uc_engine* uc = eng.uc()) uc_reg_read(uc, UC_ARM_REG_LR, &callerLr);
+        Log("GuestHeap: free(0x%x) from guest LR=0x%x", ptr, callerLr);
+    }
+    eng.heap().Free(ptr);
+    return 0;
+}
+uint32_t Shim_calloc(GuestEngine& eng, uint32_t nmemb, uint32_t size, uint32_t, uint32_t, uint32_t) {
+    // 2026-09-19: GuestHeap::Alloc no longer zero-fills (it used to memset
+    // the whole rounded-up class block on every malloc - see its own
+    // comment), so calloc has to do it itself, which is where the cost
+    // belongs. Overflow-checked: nmemb*size in 32-bit guest arithmetic can
+    // wrap, and a wrapped-small allocation followed by a full-size memset
+    // would be a heap overflow.
+    uint64_t total = (uint64_t)nmemb * (uint64_t)size;
+    if (total > 0xFFFFFFFFull) {
+        Log("Shim_calloc: %u * %u overflows 32 bits - returning NULL", nmemb, size);
+        return 0;
+    }
+    GuestAddr addr = eng.heap().Alloc((uint32_t)total);
+    if (addr && total) memset(eng.G2H(addr), 0, (size_t)total);
+    return addr;
+}
+uint32_t Shim_realloc(GuestEngine& eng, uint32_t ptr, uint32_t size, uint32_t, uint32_t, uint32_t) {
+    // No real "grow in place" support in GuestHeap (see its own class
+    // comment - no coalescing) - always relocates. Correct but wasteful;
+    // fine for a prototype's expected allocation volume.
+    // 2026-09-19: the old block's exact size is now available (GuestHeap
+    // stores it per block and exposes BlockSize), so this copies the real
+    // min(oldSize,newSize). It used to copy `size` unconditionally, which on
+    // a SHRINKING realloc read past the end of the old block - harmless in
+    // practice only because the arena is one contiguous mapping.
+    uint32_t oldSize = ptr ? eng.heap().BlockSize(ptr) : 0;
+    GuestAddr newAddr = eng.heap().Alloc(size);
+    if (ptr && newAddr) {
+        uint32_t toCopy = (oldSize && oldSize < size) ? oldSize : size;
+        memcpy(eng.G2H(newAddr), eng.G2H(ptr), toCopy);
+    }
+    if (ptr) eng.heap().Free(ptr);
+    return newAddr;
+}
+
+uint32_t Shim_strlen(GuestEngine& eng, uint32_t s, uint32_t, uint32_t, uint32_t, uint32_t) {
+    if (!s) return 0;
+    uint32_t len = (uint32_t)strlen((const char*)eng.G2H(s));
+    // Diagnostic (2026-09-17, ARM64_TRANSLATION_LAYER.md - the 0x1e0 wild-jump
+    // chase). strlen() runs on the HOST over the translated pointer, so an
+    // unterminated guest string doesn't fault - it just keeps scanning
+    // forward through whatever else lives in the shared host_region_ arena
+    // until it happens to hit a stray zero byte, potentially megabytes later.
+    // That exact symptom (a huge, ever-doubling "length" feeding into a
+    // runaway std::string/streambuf reallocation) is what's driving the
+    // 0x1e0 crash - flagging any suspiciously large result (not the normal
+    // case, so cheap to check) to catch it at the source instead of several
+    // frames downstream.
+    if (len > 4096) {
+        uint32_t callerLr = 0;
+        if (uc_engine* uc = eng.uc()) uc_reg_read(uc, UC_ARM_REG_LR, &callerLr);
+        Log("GuestEngine: Shim_strlen: suspiciously large result - s=0x%x len=%u from guest LR=0x%x",
+            s, len, callerLr);
+    }
+    return len;
+}
+uint32_t Shim_strcmp(GuestEngine& eng, uint32_t a, uint32_t b, uint32_t, uint32_t, uint32_t) {
+    return (uint32_t)(int32_t)strcmp((const char*)eng.G2H(a), (const char*)eng.G2H(b));
+}
+uint32_t Shim_strcpy(GuestEngine& eng, uint32_t dst, uint32_t src, uint32_t, uint32_t, uint32_t) {
+    strcpy((char*)eng.G2H(dst), (const char*)eng.G2H(src));
+    return dst;
+}
+uint32_t Shim_strncpy(GuestEngine& eng, uint32_t dst, uint32_t src, uint32_t n, uint32_t, uint32_t) {
+    strncpy((char*)eng.G2H(dst), (const char*)eng.G2H(src), n);
+    return dst;
+}
+uint32_t Shim_tolower(GuestEngine&, uint32_t c, uint32_t, uint32_t, uint32_t, uint32_t) {
+    return (uint32_t)tolower((int)c);
+}
+
+// pthread_mutexattr_t is entirely ignored (see pthread_shim.h's gap list -
+// every guest mutex is a real std::recursive_mutex regardless of the attr
+// type requested, so there's nothing for init/settype/destroy to actually
+// configure); these three stay plain always-succeed no-ops.
+uint32_t Shim_pthread_noop_success(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return 0; }
+
+uint32_t Shim_raise(GuestEngine&, uint32_t sig, uint32_t, uint32_t, uint32_t, uint32_t) {
+    Log("import_shims: guest code called raise(%u) - not delivering a real signal to the guest "
+        "(no guest signal handling exists), returning as if handled", sig);
+    return 0;
+}
+
+// EA's own thin JNIEnv/classloader-caching wrappers (EA::Nimble::getEnv/
+// findClass) - genuinely external to libapp.so itself (normally provided by
+// libNimble.so, which - like libapp.so - has no arm64-v8a build and isn't
+// loaded into the emulator). Implemented directly against JniShim instead
+// of emulating libNimble.so's own code, since these two are simple enough
+// to reimplement natively (same "wrap the API, don't translate the
+// implementation" principle as the rest of this shim layer).
+uint32_t Shim_ea_nimble_getEnv(GuestEngine& eng, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) {
+    return JniShim::Instance().BuildGuestJNIEnv(eng);
+}
+uint32_t Shim_ea_nimble_findClass(GuestEngine& eng, uint32_t namePtr, uint32_t, uint32_t, uint32_t, uint32_t) {
+    if (!namePtr) return 0;
+    // Real JNI FindClass requires slash-separated names ("com/ea/..."), but
+    // callers of this EA convenience wrapper pass dot-separated ones
+    // ("com.ea.nimble.Log", confirmed live via a CheckJNI "illegal class
+    // name" abort this session) - the real libNimble.so implementation
+    // clearly did this same conversion internally before calling the real
+    // FindClass, so this reimplementation must too.
+    std::string name = (const char*)eng.G2H(namePtr);
+    for (char& c : name) if (c == '.') c = '/';
+    jclass c = JniShim::Instance().RealEnv()
+                   ? JniShim::Instance().FindClassWithFallback(JniShim::Instance().RealEnv(), name)
+                   : nullptr;
+    return c ? JniShim::Instance().handles().Alloc(c) : 0;
+}
+
+uint32_t Shim_cxa_guard_acquire(GuestEngine& eng, uint32_t guard, uint32_t, uint32_t, uint32_t, uint32_t) {
+    uint8_t* p = (uint8_t*)eng.G2H(guard);
+    return (*p == 0) ? 1u : 0u; // 1 = "you run the initializer", 0 = "already done"
+}
+uint32_t Shim_cxa_guard_release(GuestEngine& eng, uint32_t guard, uint32_t, uint32_t, uint32_t, uint32_t) {
+    *(uint8_t*)eng.G2H(guard) = 1;
+    return 0;
+}
+uint32_t Shim_cxa_guard_abort(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return 0; }
+uint32_t Shim_cxa_atexit(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return 0; }
+uint32_t Shim_cxa_pure_virtual(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) {
+    Log("import_shims: __cxa_pure_virtual called (guest called a pure-virtual method) - "
+        "this is a real bug signal, not expected in normal operation");
+    return 0;
+}
+uint32_t Shim_abort(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) {
+    Log("import_shims: guest code called abort() - NOT actually aborting the host process "
+        "(would take down the whole app); this shim just logs and returns, so guest execution "
+        "after this point is running past what the real binary would have allowed. See this "
+        "file's own top-of-file gap notes.");
+    return 0;
+}
+uint32_t Shim_dladdr(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return 0; } // always "not found"
+
+// ---- Single-precision math (softfp - see this file's top comment) ----
+// All take/return one or two GLfloat-shaped 32-bit register values; no
+// alignment concerns since none of these have a double-precision (8-byte)
+// parameter to worry about.
+#define MATH1F_SHIM(name)                                                                       \
+    uint32_t Shim_##name(GuestEngine&, uint32_t r0, uint32_t, uint32_t, uint32_t, uint32_t) {    \
+        float x, r;                                                                              \
+        memcpy(&x, &r0, 4);                                                                       \
+        r = name(x);                                                                              \
+        uint32_t bits;                                                                            \
+        memcpy(&bits, &r, 4);                                                                     \
+        return bits;                                                                              \
+    }
+#define MATH2F_SHIM(name)                                                                        \
+    uint32_t Shim_##name(GuestEngine&, uint32_t r0, uint32_t r1, uint32_t, uint32_t, uint32_t) {  \
+        float x, y, r;                                                                            \
+        memcpy(&x, &r0, 4);                                                                       \
+        memcpy(&y, &r1, 4);                                                                       \
+        r = name(x, y);                                                                            \
+        uint32_t bits;                                                                            \
+        memcpy(&bits, &r, 4);                                                                     \
+        return bits;                                                                              \
+    }
+MATH1F_SHIM(acosf)
+MATH1F_SHIM(asinf)
+MATH1F_SHIM(ceilf)
+MATH1F_SHIM(cosf)
+MATH1F_SHIM(expf)
+MATH1F_SHIM(floorf)
+MATH1F_SHIM(roundf)
+MATH1F_SHIM(sinf)
+MATH1F_SHIM(sqrtf)
+MATH1F_SHIM(tanf)
+MATH2F_SHIM(atan2f)
+MATH2F_SHIM(fmodf)
+MATH2F_SHIM(powf)
+#undef MATH1F_SHIM
+#undef MATH2F_SHIM
+
+uint32_t Shim_atoi(GuestEngine& eng, uint32_t s, uint32_t, uint32_t, uint32_t, uint32_t) {
+    return s ? (uint32_t)atoi((const char*)eng.G2H(s)) : 0;
+}
+uint32_t Shim_memcmp(GuestEngine& eng, uint32_t a, uint32_t b, uint32_t n, uint32_t, uint32_t) {
+    return (uint32_t)(int32_t)memcmp(eng.G2H(a), eng.G2H(b), n);
+}
+uint32_t Shim_memset(GuestEngine& eng, uint32_t dst, uint32_t c, uint32_t n, uint32_t, uint32_t) {
+    memset(eng.G2H(dst), (int)c, n);
+    return dst;
+}
+uint32_t Shim_strncmp(GuestEngine& eng, uint32_t a, uint32_t b, uint32_t n, uint32_t, uint32_t) {
+    return (uint32_t)(int32_t)strncmp((const char*)eng.G2H(a), (const char*)eng.G2H(b), n);
+}
+uint32_t Shim_strrchr(GuestEngine& eng, uint32_t s, uint32_t c, uint32_t, uint32_t, uint32_t) {
+    if (!s) return 0;
+    char* p = strrchr((char*)eng.G2H(s), (int)c);
+    return p ? eng.H2G(p) : 0;
+}
+uint32_t Shim_strstr(GuestEngine& eng, uint32_t hay, uint32_t needle, uint32_t, uint32_t, uint32_t) {
+    if (!hay || !needle) return 0;
+    char* p = strstr((char*)eng.G2H(hay), (const char*)eng.G2H(needle));
+    return p ? eng.H2G(p) : 0;
+}
+uint32_t Shim_toupper(GuestEngine&, uint32_t c, uint32_t, uint32_t, uint32_t, uint32_t) {
+    return (uint32_t)toupper((int)c);
+}
+uint32_t Shim_lrand48(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) {
+    return (uint32_t)lrand48();
+}
+
+// clock_gettime/nanosleep/time all write into a guest-addressed struct/
+// pointer - direct G2H translation, same as everywhere else in this file.
+// Real host struct layouts (`struct timespec`) are ABI-identical between
+// 32-bit and 64-bit (two `long`-ish fields that both fit this project's
+// existing 32-bit-guest assumption closely enough for timing purposes,
+// though a fully correct implementation would need to know the guest's own
+// expected struct timespec field widths - approximated here, documented).
+uint32_t Shim_clock_gettime(GuestEngine& eng, uint32_t clockId, uint32_t tsPtr, uint32_t, uint32_t, uint32_t) {
+    struct timespec ts{};
+    int rc = clock_gettime((clockid_t)clockId, &ts);
+    if (tsPtr) {
+        uint32_t sec = (uint32_t)ts.tv_sec, nsec = (uint32_t)ts.tv_nsec;
+        memcpy(eng.G2H(tsPtr), &sec, 4);
+        memcpy((uint8_t*)eng.G2H(tsPtr) + 4, &nsec, 4);
+    }
+    return (uint32_t)rc;
+}
+uint32_t Shim_nanosleep(GuestEngine& eng, uint32_t reqPtr, uint32_t, uint32_t, uint32_t, uint32_t) {
+    if (!reqPtr) return -1;
+    uint32_t sec = 0, nsec = 0;
+    memcpy(&sec, eng.G2H(reqPtr), 4);
+    memcpy(&nsec, (uint8_t*)eng.G2H(reqPtr) + 4, 4);
+    struct timespec req{(time_t)sec, (long)nsec};
+    return (uint32_t)nanosleep(&req, nullptr);
+}
+uint32_t Shim_time(GuestEngine& eng, uint32_t tPtr, uint32_t, uint32_t, uint32_t, uint32_t) {
+    time_t t = time(nullptr);
+    if (tPtr) { uint32_t v = (uint32_t)t; memcpy(eng.G2H(tPtr), &v, 4); }
+    return (uint32_t)t;
+}
+
+uint32_t Shim_android_log_write(GuestEngine& eng, uint32_t prio, uint32_t tagPtr, uint32_t msgPtr, uint32_t, uint32_t) {
+    const char* tag = tagPtr ? (const char*)eng.G2H(tagPtr) : "libapp";
+    const char* msg = msgPtr ? (const char*)eng.G2H(msgPtr) : "";
+    return (uint32_t)__android_log_write((int)prio, tag, msg);
+}
+
+// `thread_local` (not a single shared array) - now that real guest threads
+// exist (emu/pthread_shim.cpp), a flat shared array would let one guest
+// thread's pthread_setspecific silently clobber every other thread's value
+// for the same key, which is exactly backwards from real TLS semantics. Key
+// ALLOCATION (g_tlsKeyCount) is still process-wide/shared, as real bionic's
+// is - only the per-key VALUES are per-thread.
+constexpr int kMaxTlsKeys = 64;
+thread_local uint32_t g_tlsValues[kMaxTlsKeys] = {};
+std::mutex g_tlsKeyCountMutex;
+int g_tlsKeyCount = 0;
+uint32_t Shim_pthread_key_create(GuestEngine& eng, uint32_t keyOutPtr, uint32_t, uint32_t, uint32_t, uint32_t) {
+    std::lock_guard<std::mutex> lock(g_tlsKeyCountMutex);
+    if (g_tlsKeyCount >= kMaxTlsKeys) return -1;
+    uint32_t key = (uint32_t)g_tlsKeyCount++;
+    if (keyOutPtr) memcpy(eng.G2H(keyOutPtr), &key, 4);
+    return 0;
+}
+uint32_t Shim_pthread_key_delete(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) { return 0; }
+uint32_t Shim_pthread_getspecific(GuestEngine&, uint32_t key, uint32_t, uint32_t, uint32_t, uint32_t) {
+    return (key < (uint32_t)kMaxTlsKeys) ? g_tlsValues[key] : 0;
+}
+uint32_t Shim_pthread_setspecific(GuestEngine&, uint32_t key, uint32_t value, uint32_t, uint32_t, uint32_t) {
+    if (key < (uint32_t)kMaxTlsKeys) g_tlsValues[key] = value;
+    return 0;
+}
+// Per-real-host-thread fake id (was a single hardcoded `1` when the guest
+// was single-threaded) - a thread_local counter assigned once per thread on
+// first call, distinct across real guest threads, still opaque/never a real
+// bionic pthread_t.
+uint32_t Shim_pthread_self(GuestEngine&, uint32_t, uint32_t, uint32_t, uint32_t, uint32_t) {
+    static std::atomic<uint32_t> nextId{1};
+    static thread_local uint32_t id = nextId.fetch_add(1);
+    return id;
+}
+
+} // namespace
+
+void RegisterCoreImportShims(GuestEngine& engine) {
+    engine.RegisterImportShim("__aeabi_memcpy", Shim_aeabi_memcpy);
+    engine.RegisterImportShim("__aeabi_memcpy4", Shim_aeabi_memcpy);
+    engine.RegisterImportShim("__aeabi_memcpy8", Shim_aeabi_memcpy);
+    engine.RegisterImportShim("__memcpy_chk", Shim_memcpy_chk);
+    engine.RegisterImportShim("newlocale", Shim_newlocale);
+    engine.RegisterImportShim("uselocale", Shim_uselocale);
+    engine.RegisterImportShim("freelocale", Shim_freelocale);
+    engine.RegisterImportShim("__aeabi_memmove", Shim_aeabi_memmove);
+    engine.RegisterImportShim("__aeabi_memmove4", Shim_aeabi_memmove);
+    engine.RegisterImportShim("__aeabi_memmove8", Shim_aeabi_memmove);
+    engine.RegisterImportShim("__aeabi_memset", Shim_aeabi_memset);
+    engine.RegisterImportShim("__aeabi_memset4", Shim_aeabi_memset);
+    engine.RegisterImportShim("__aeabi_memset8", Shim_aeabi_memset);
+    engine.RegisterImportShim("__aeabi_memclr", Shim_aeabi_memclr);
+    engine.RegisterImportShim("__aeabi_memclr4", Shim_aeabi_memclr);
+    engine.RegisterImportShim("__aeabi_memclr8", Shim_aeabi_memclr);
+    engine.RegisterImportShim("memcpy", Shim_aeabi_memcpy);
+    engine.RegisterImportShim("memmove", Shim_aeabi_memmove);
+
+    engine.RegisterImportShim("malloc", Shim_malloc);
+    engine.RegisterImportShim("free", Shim_free);
+    engine.RegisterImportShim("calloc", Shim_calloc);
+    engine.RegisterImportShim("realloc", Shim_realloc);
+
+    engine.RegisterImportShim("strlen", Shim_strlen);
+    engine.RegisterImportShim("strcmp", Shim_strcmp);
+    engine.RegisterImportShim("strcpy", Shim_strcpy);
+    engine.RegisterImportShim("strncpy", Shim_strncpy);
+    engine.RegisterImportShim("tolower", Shim_tolower);
+
+    engine.RegisterImportShim("pthread_mutexattr_init", Shim_pthread_noop_success);
+    engine.RegisterImportShim("pthread_mutexattr_settype", Shim_pthread_noop_success);
+    engine.RegisterImportShim("pthread_mutexattr_destroy", Shim_pthread_noop_success);
+    // Real pthread_create/join/mutex_*/cond_* shims are registered by
+    // RegisterPthreadImportShims (emu/pthread_shim.cpp) - the caller (see
+    // main.cpp) calls that after this function.
+    engine.RegisterImportShim("raise", Shim_raise);
+
+    engine.RegisterImportShim("_ZN2EA6Nimble6getEnvEv", Shim_ea_nimble_getEnv);
+    engine.RegisterImportShim("_ZN2EA6Nimble9findClassEPKc", Shim_ea_nimble_findClass);
+
+    engine.RegisterImportShim("__cxa_guard_acquire", Shim_cxa_guard_acquire);
+    engine.RegisterImportShim("__cxa_guard_release", Shim_cxa_guard_release);
+    engine.RegisterImportShim("__cxa_guard_abort", Shim_cxa_guard_abort);
+    engine.RegisterImportShim("__cxa_atexit", Shim_cxa_atexit);
+    engine.RegisterImportShim("__cxa_pure_virtual", Shim_cxa_pure_virtual);
+    engine.RegisterImportShim("abort", Shim_abort);
+    engine.RegisterImportShim("dladdr", Shim_dladdr);
+
+    engine.RegisterImportShim("acosf", Shim_acosf);
+    engine.RegisterImportShim("asinf", Shim_asinf);
+    engine.RegisterImportShim("ceilf", Shim_ceilf);
+    engine.RegisterImportShim("cosf", Shim_cosf);
+    engine.RegisterImportShim("expf", Shim_expf);
+    engine.RegisterImportShim("floorf", Shim_floorf);
+    engine.RegisterImportShim("roundf", Shim_roundf);
+    engine.RegisterImportShim("sinf", Shim_sinf);
+    engine.RegisterImportShim("sqrtf", Shim_sqrtf);
+    engine.RegisterImportShim("tanf", Shim_tanf);
+    engine.RegisterImportShim("atan2f", Shim_atan2f);
+    engine.RegisterImportShim("fmodf", Shim_fmodf);
+    engine.RegisterImportShim("powf", Shim_powf);
+
+    engine.RegisterImportShim("atoi", Shim_atoi);
+    engine.RegisterImportShim("memcmp", Shim_memcmp);
+    engine.RegisterImportShim("memset", Shim_memset);
+    engine.RegisterImportShim("strncmp", Shim_strncmp);
+    engine.RegisterImportShim("strrchr", Shim_strrchr);
+    engine.RegisterImportShim("strstr", Shim_strstr);
+    engine.RegisterImportShim("toupper", Shim_toupper);
+    engine.RegisterImportShim("lrand48", Shim_lrand48);
+
+    engine.RegisterImportShim("clock_gettime", Shim_clock_gettime);
+    engine.RegisterImportShim("nanosleep", Shim_nanosleep);
+    engine.RegisterImportShim("time", Shim_time);
+
+    engine.RegisterImportShim("__android_log_write", Shim_android_log_write);
+
+    engine.RegisterImportShim("pthread_key_create", Shim_pthread_key_create);
+    engine.RegisterImportShim("pthread_key_delete", Shim_pthread_key_delete);
+    engine.RegisterImportShim("pthread_getspecific", Shim_pthread_getspecific);
+    engine.RegisterImportShim("pthread_setspecific", Shim_pthread_setspecific);
+    engine.RegisterImportShim("pthread_self", Shim_pthread_self);
+}

mpcore/src/main/cpp/emu/import_shims.h

@@ -0,0 +1,15 @@
+#pragma once
+
+#include "guest_engine.h"
+
+// Registers the small, deliberately-bounded set of real import shims this
+// prototype implements (see import_shims.cpp for the list and the
+// class-level notes in that file about what's NOT covered yet - notably
+// libc++ locale/iostream/RTTI beyond trivial __cxa_guard/pure_virtual
+// stubs). Real pthread_create/join/mutex/cond support is registered
+// separately by RegisterPthreadImportShims (emu/pthread_shim.h) - call both
+// (see main.cpp). Anything not registered by either still gets a guest stub
+// address (so relocations always resolve to *something*), it just logs
+// "unresolved import" once and returns 0 instead of crashing - see
+// GuestEngine::ResolveOrCreateImportStub / import_stub_dispatch_cb.
+void RegisterCoreImportShims(GuestEngine& engine);

mpcore/src/main/cpp/emu/jni_shim.h

@@ -0,0 +1,225 @@
+#pragma once
+
+// Guest-visible JNIEnv - lets guest code (running inside GuestEngine) call
+// back into the REAL Android JVM, e.g. from libapp.so's own real
+// nativeOnCreate/JNI_OnLoad now that they're invoked via CallGuestFunction
+// instead of being no-op host stubs. See ARM64_TRANSLATION_LAYER.md's
+// "JNI upcalls" section - this is the "least risky, most mechanical" piece
+// that doc predicted, now actually built.
+//
+// Mechanism: builds a real `struct JNINativeInterface` layout (233 function-
+// pointer slots, exact order extracted from this NDK's own jni.h) in guest
+// memory, one stub guest-address per slot (same UC_HOOK_CODE "replace and
+// return via LR" pattern as GuestEngine's import stubs / InstallTrampolineHook).
+// When guest code calls env->FindClass(...), Unicorn's hook fires at that
+// slot's stub address, the dispatcher reads the incoming args (r1.. plus
+// stack, since r0 is always the guest JNIEnv* itself), forwards to the REAL
+// host JNIEnv, and translates the result back into a guest-visible handle.
+//
+// Reference-shaped JNI values (jobject/jclass/jstring/jarray/jmethodID/
+// jfieldID/jthrowable/jweak) are all real 64-bit-ish host values on this
+// (64-bit ART) runtime and cannot fit in a 32-bit guest register - JniHandleTable
+// hands out small sequential 32-bit guest handles and resolves them back,
+// the same "handle indirection" every ARM-on-64-bit-host JNI bridge needs.
+//
+// Deliberately bounded scope (documented, not silent): only ~25 of the 233
+// slots have real implementations (the ones covering class/method/field
+// lookup, 0-argument method calls, strings, refs, exceptions - see
+// jni_shim.cpp's own top comment for the exact list and the known gaps in
+// Call*Method argument marshaling for methods that take parameters). Every
+// other slot gets a guest stub that logs "unresolved JNI slot N (name)" once
+// and returns 0, exactly matching GuestEngine's own import-stub philosophy.
+
+#include <jni.h>
+#include <vector>
+#include <mutex>
+#include <thread>
+#include <atomic>
+#include "guest_engine.h"
+
+// Bidirectional 32-bit guest handle <-> real 64-bit-capable JNI reference.
+// Never reuses/frees slots in this prototype (documented leak, acceptable
+// for a short test run - see class comment above). Mutex-guarded - now that
+// real guest threads exist (see emu/pthread_shim.h), more than one could in
+// principle resolve/allocate a JNI handle concurrently (e.g. two threads
+// each calling a Call*Method JNI slot at the same time).
+//
+// Each slot also records the real host thread that created it and whether
+// it's a durable ("global") reference. Real JNI local references are only
+// valid on the thread (and, strictly, the native-call frame) that created
+// them - reused elsewhere they're either NULL (harmless) or a live-looking
+// pointer to a DIFFERENT, unrelated real object, which real ART's CheckJNI
+// hard-aborts the whole process on (confirmed live 2026-09-05 - see
+// ARM64_TRANSLATION_LAYER.md's "invalid local jclass" investigation: a guest
+// C++ helper cached a bare local jclass once on the main thread and reused
+// it ~90s later from the GLThread inside RunLoop.nativeOnRunLoopTick - a
+// real bug in that ~2013 EA code, not this shim, but one this shim can
+// detect and degrade gracefully instead of crashing the whole process).
+// IsSafeToUseFromCurrentThread lets a call site check this BEFORE handing
+// the resolved pointer to any real JNI function - deliberately never asks
+// ART itself (e.g. via GetObjectRefType), since CheckJNI validates every
+// reference argument to every JNI function, including that one, so there is
+// no real-JNI-call-based way to probe a reference's validity that doesn't
+// risk aborting on exactly the kind of stale reference being checked for.
+class JniHandleTable {
+public:
+    uint32_t Alloc(void* real, bool isGlobal = false);
+    void* Resolve(uint32_t handle) const;
+    // Fix (2026-09-17, ARM64_TRANSLATION_LAYER.md - the SIGABRT-in-GLThread
+    // chase, ROOT CAUSE). This class's own comment above already called out
+    // "and, strictly, the native-call frame" as part of what makes a local
+    // ref valid - but the implementation only ever checked the owning
+    // THREAD, never the owning CALL. Confirmed live: `nativeOnRunLoopTick`
+    // is called repeatedly, ONCE PER FRAME, on the SAME real "GLThread" -
+    // each call is its own fresh JNI native-method invocation with its own
+    // local-ref frame (real_native_call.h's CallRealNative calls
+    // SetRealEnv(env) on every single entry, confirming this), so a jclass
+    // cached during one tick and reused during a LATER tick is stale THE
+    // MOMENT the tick that created it returns to Java - even though it's
+    // the exact same host thread throughout. BumpCallEpoch() is called
+    // from SetRealEnv (see its own comment) to mark each such boundary;
+    // IsSafeToUseFromCurrentThread now checks BOTH the owning thread AND
+    // the owning epoch.
+    bool IsSafeToUseFromCurrentThread(uint32_t handle) const;
+    //
+    // Corrected 2026-09-21 (task #67): the epoch used to be ONE process-wide
+    // counter. That was indistinguishable from correct while only one host
+    // thread ever crossed into JNI - but a local ref's lifetime is scoped to
+    // a native call ON ITS OWN THREAD, and a bump from a different thread has
+    // no business invalidating it.
+    //
+    // It stopped being academic the moment the FMOD audio bridge began
+    // calling in from FMODAudioDevice's AudioTrack thread every 100 ms: each
+    // of those bumps invalidated the refs GLThread was holding mid-call, and
+    // the process aborted with "JNI DETECTED ERROR IN APPLICATION: jfieldID
+    // was NULL" inside GLThread. Per-thread is both the fix and the more
+    // accurate model - no atomics needed either, since a thread's own epoch
+    // is only ever read and written by that thread.
+    static void BumpCallEpoch() { ++t_callEpoch; }
+    static uint32_t CurrentCallEpoch() { return t_callEpoch; }
+
+private:
+    static thread_local uint32_t t_callEpoch;
+    struct Entry {
+        void* real = nullptr;
+        std::thread::id owner;
+        bool isGlobal = false;
+        uint32_t epoch = 0; // the OWNING THREAD's epoch at Alloc() time - see IsSafeToUseFromCurrentThread
+    };
+    mutable std::mutex mutex_;
+    std::vector<Entry> table_{Entry{}}; // index 0 reserved for guest NULL
+};
+
+class JniShim {
+public:
+    static JniShim& Instance();
+
+    // Builds the guest JNIEnv structure (once) and returns its guest
+    // address - pass this as the first (r0) argument to any real guest
+    // function that expects a JNIEnv*.
+    GuestAddr BuildGuestJNIEnv(GuestEngine& engine);
+
+    // Wraps a range of GUEST memory in a real Java direct ByteBuffer and
+    // returns the guest handle for it, registered so that the guest's own
+    // GetDirectBufferAddress resolves it back to `guestAddr`.
+    //
+    // Needed because GetDirectBufferAddress can only answer for buffers this
+    // shim created (see its own comment): a ByteBuffer that Java allocated
+    // lives at a host address the guest cannot reach. Anything handing guest
+    // code a Java-allocated buffer therefore has to bounce through one of
+    // these - the same shape as the AndroidBitmap_lockPixels fix.
+    uint32_t NewGuestBackedDirectBuffer(GuestEngine& engine, GuestAddr guestAddr, uint32_t capacity);
+
+    // Builds a minimal guest JavaVM (8-slot JNIInvokeInterface) - only
+    // GetEnv and AttachCurrentThread are real (both just return the same
+    // guest JNIEnv from BuildGuestJNIEnv - this shim only ever has one
+    // "thread"/env, see SetRealEnv's own comment); DestroyJavaVM/
+    // DetachCurrentThread/AttachCurrentThreadAsDaemon are logged no-ops.
+    // Needed to call libapp.so's own real JNI_OnLoad(JavaVM*, void*).
+    GuestAddr BuildGuestJavaVM(GuestEngine& engine);
+
+    // Must be called before each top-level CallGuestFunction into guest
+    // code that might call back into Java - stores the REAL, currently
+    // valid JNIEnv* for the CALLING thread (JNIEnv* is only valid on the
+    // thread that obtained it - this is `thread_local` specifically so that
+    // holds, now that real guest pthreads exist - see emu/pthread_shim.h).
+    // Every current call site (main.cpp / game_lifecycle_stubs*.cpp) still
+    // only ever runs on the main/UI thread, so this doesn't change today's
+    // behavior - it just means a guest worker thread that starts calling
+    // into JNI won't silently corrupt/steal the main thread's slot; it will
+    // need to set its OWN via AttachCurrentThread first (see
+    // Impl_Vm_AttachCurrentThread in jni_shim.cpp), same as real Android JNI
+    // requires.
+    // Fix (2026-09-17, ARM64_TRANSLATION_LAYER.md - the SIGSEGV-in-GLThread
+    // chase, directly following on from this class's own comment above
+    // about a guest worker thread needing to AttachCurrentThread first).
+    // Confirmed live: a real, engine-spawned "GLThread" pthread eventually
+    // calls a JNI slot (GetMethodID) with its own real_env_ still null -
+    // this thread's slot was never populated, because
+    // Impl_Vm_AttachCurrentThread (jni_shim.cpp) only ever built a FAKE
+    // guest JNIEnv handle and never actually attached the calling HOST
+    // thread to the real JVM at all. Caches the process-wide `JavaVM*` the
+    // first time any thread supplies a real env (JavaVM* itself, unlike
+    // JNIEnv*, is valid across every thread) so Impl_Vm_AttachCurrentThread
+    // can call the REAL AttachCurrentThread for whichever host thread asks.
+    void SetRealEnv(JNIEnv* env) {
+        real_env_ = env;
+        if (env && !real_vm_) {
+            env->GetJavaVM(&real_vm_);
+        }
+        // Fix (2026-09-17) - see JniHandleTable::BumpCallEpoch's own
+        // comment. This call site is exactly "a new top-level native call
+        // is beginning" (real_native_call.h's CallRealNative calls this on
+        // every single entry) - every local ref handed out during the
+        // PREVIOUS call is now stale, whether or not it's the same thread.
+        if (env) handles_.BumpCallEpoch();
+    }
+    // Defensive fallback (same fix): if this HOST thread's own real_env_ is
+    // still null (guest code never called AttachCurrentThread on this
+    // thread, or it hasn't run yet), lazily attach for real here too,
+    // rather than only relying on Impl_Vm_AttachCurrentThread being the
+    // one and only path that populates it. Matches real Android's own
+    // forgiving behavior for JNI calls arriving on a not-yet-attached
+    // native thread. Safe to call from any thread; no-ops if there's no
+    // real JavaVM cached yet (nothing to attach to) or the thread is
+    // already attached (real AttachCurrentThread is itself idempotent).
+    JNIEnv* RealEnv() {
+        if (!real_env_ && real_vm_) {
+            JNIEnv* env = nullptr;
+            if (real_vm_->AttachCurrentThread(&env, nullptr) == JNI_OK && env) {
+                real_env_ = env;
+            }
+        }
+        return real_env_;
+    }
+    JavaVM* RealVm() const { return real_vm_; }
+
+    JniHandleTable& handles() { return handles_; }
+
+    // Classic Android JNI gotcha: FindClass only sees app classes correctly
+    // when called from the thread that originally loaded the native
+    // library (or one attached the same way) - called from any other
+    // thread (e.g. the real engine's GLThread, confirmed live this session
+    // via a "JNI DETECTED ERROR...GetMethodID received NULL jclass" abort
+    // traced back to a failed FindClass inside nativeSurfaceCreated) it
+    // silently only sees bootclasspath classes. Standard fix: cache the
+    // app's real ClassLoader once (from any already-reachable app object,
+    // on the main thread) and fall back to ClassLoader.loadClass() when a
+    // direct FindClass call fails. Call once, early (LoadEmulatedLibapp).
+    void CacheClassLoader(JNIEnv* env, jobject anyAppObject);
+    // Resolves `name` (slash-separated, real JNI FindClass convention) via
+    // a direct FindClass first, falling back to the cached ClassLoader if
+    // that fails/throws - this is what Impl_FindClass (jni_shim.cpp) and
+    // the EA::Nimble::findClass shim (import_shims.cpp) both call through.
+    jclass FindClassWithFallback(JNIEnv* env, const std::string& slashName);
+
+private:
+    JniShim() = default;
+    static thread_local JNIEnv* real_env_;
+    JavaVM* real_vm_ = nullptr; // process-wide, NOT thread_local - see SetRealEnv's own comment
+    JniHandleTable handles_;
+    GuestAddr guest_env_ = 0;
+    GuestAddr guest_vm_ = 0;
+    jobject class_loader_ = nullptr; // global ref
+    jmethodID load_class_method_ = nullptr;
+};

mpcore/src/main/cpp/emu/libc_shims.h

@@ -0,0 +1,42 @@
+#pragma once
+
+#include "guest_engine.h"
+
+// Real implementations for the ~180 basic libc/POSIX imports libapp.so
+// actually calls that import_shims.cpp didn't cover (string.h/ctype.h/
+// math.h/stdio.h, POSIX file I/O, time.h, process/signal, dlopen family,
+// network/socket, pthread extras, sem_*, __aeabi_* ARM EABI helpers, and a
+// handful of Android/EGL/GLES-extension odds and ends).
+//
+// Root cause this file exists: EVERY one of these previously fell through
+// to the generic "unresolved import, log once, return 0" handler. That's
+// not a harmless gap - guest code that reasonably assumes fopen()/getenv()/
+// strdup() succeeded and got a real pointer back, then dereferences a
+// silently-substituted NULL/0, is undefined behavior from that point on -
+// this session traced a real, hard-to-diagnose memory corruption bug back
+// to exactly this pattern (a burst of unresolved fread/fseek/fwrite/RTTI
+// symbols during libc++ runtime bootstrap, immediately followed by
+// something writing garbage into unrelated guest memory). "Return 0 and
+// hope" is not an acceptable default for anything actually called - see
+// ARM64_TRANSLATION_LAYER.md's "go through all the imports" entry.
+//
+// Same marshaling conventions as import_shims.cpp throughout: pointer args
+// are guest addresses, G2H-translated before use; functions returning a
+// pointer INTO an already-G2H'd buffer (strchr, memchr, ...) H2G-translate
+// the result back; functions returning a host-owned string (strerror,
+// getenv, strdup, ...) copy it into a freshly heap-allocated guest buffer
+// (same pattern as jni_shim.cpp's GetStringUTFChars); FILE*/DIR* (real host
+// pointers, don't fit a 32-bit guest register) go through small handle
+// tables, same shape as JniHandleTable.
+void RegisterLibcImportShims(GuestEngine& engine);
+
+// A GuestEngine::DataSymbolSetupFn (register via
+// engine.RegisterDataSymbolSetup BEFORE engine.LoadImage, same as
+// rtti_shims.h's SetupRttiDataSymbols) - builds real guest-visible data for
+// the handful of libc DATA symbols (not callable functions) this sweep
+// turned up: __stack_chk_guard (a stack-canary value - see its own
+// comment for why any stable value works), timezone/tzname (mirrored from
+// the real host globals, refreshed on every tzset() call), and __sF (real
+// FILE* handles for stdin/stdout/stderr, via the same handle table
+// fopen/fclose/etc already use).
+void SetupLibcDataSymbols(GuestEngine& engine);

mpcore/src/main/cpp/emu/name_lookup_accel.cpp

@@ -0,0 +1,202 @@
+#include "name_lookup_accel.h"
+
+#include "guest_engine.h"
+#include "../util/util.h"
+
+#include <atomic>
+#include <cstring>
+#include <map>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+
+namespace name_lookup_accel {
+namespace {
+
+constexpr uint32_t kOffCacheFlag = 8;
+constexpr uint32_t kOffEntriesA = 196;
+constexpr uint32_t kOffCountA = 200;
+constexpr uint32_t kOffEntriesB = 204;
+constexpr uint32_t kOffCountB = 220;
+constexpr uint32_t kOffPoolA = 224;
+constexpr uint32_t kOffPoolThreshold = 228;
+constexpr uint32_t kOffPoolB = 232;
+
+// Refuses to index anything implausible. A garbage count field would
+// otherwise turn the build loop into a multi-million-iteration walk over
+// arbitrary memory - the first version had no such guard and paid for it.
+constexpr uint32_t kMaxEntries = 200000;
+constexpr uint32_t kMaxNameLen = 128;
+
+struct TableCache {
+    uint32_t countA = 0;
+    uint32_t countB = 0;
+    uint32_t entriesA = 0;
+    uint32_t entriesB = 0;
+    uint32_t poolA = 0;
+    uint32_t poolB = 0;
+    uint32_t threshold = 0;
+    std::unordered_map<std::string, int32_t> byName;
+};
+
+std::mutex g_mutex;
+std::map<uint32_t, TableCache> g_tables;
+
+std::atomic<uint64_t> g_served{0};
+std::atomic<uint64_t> g_fellThrough{0};
+std::atomic<uint64_t> g_builds{0};
+
+// Every guest read goes through uc_mem_read, which FAILS on an unmapped
+// address instead of handing back a host pointer to walk off the end of the
+// region. That is the whole difference from the first attempt, which used
+// G2H plus an unbounded NUL scan and segfaulted the process.
+bool TryReadU32(uc_engine* uc, uint32_t addr, uint32_t* out) {
+    return addr && uc_mem_read(uc, addr, out, 4) == UC_ERR_OK;
+}
+
+// Bounded, fault-tolerant guest string read. Returns false if the string is
+// unterminated within kMaxNameLen or runs into unmapped memory.
+bool TryReadString(uc_engine* uc, uint32_t addr, std::string* out) {
+    if (!addr) return false;
+    out->clear();
+    for (uint32_t i = 0; i < kMaxNameLen; i++) {
+        uint8_t c = 0;
+        if (uc_mem_read(uc, addr + i, &c, 1) != UC_ERR_OK) return false;
+        if (!c) return true;
+        out->push_back((char)c);
+    }
+    return false;
+}
+
+// Resolves entry index -> the guest address of that entry's name, mirroring
+// the guest loop's own addressing (two entry arrays, and a threshold that
+// selects which of two string pools an offset belongs to).
+bool EntryNameAddr(uc_engine* uc, const TableCache& t, uint32_t index, uint32_t* out) {
+    uint32_t entry = (index >= t.countA) ? t.entriesB + (index - t.countA) * 8
+                                         : t.entriesA + index * 8;
+    uint32_t off = 0;
+    if (!TryReadU32(uc, entry, &off)) return false;
+    uint32_t base = t.poolA;
+    if (off >= t.threshold) {
+        off -= t.threshold;
+        base = t.poolB;
+    }
+    if (!base) return false;
+    *out = base + off;
+    return true;
+}
+
+// Reads the table's own descriptor fields. Returns false if anything looks
+// unreadable or implausible, in which case this layer stays out of the way.
+bool ReadTableDesc(uc_engine* uc, uint32_t self, TableCache* t) {
+    if (!TryReadU32(uc, self + kOffCountA, &t->countA)) return false;
+    if (!TryReadU32(uc, self + kOffCountB, &t->countB)) return false;
+    if (!TryReadU32(uc, self + kOffEntriesA, &t->entriesA)) return false;
+    if (!TryReadU32(uc, self + kOffEntriesB, &t->entriesB)) return false;
+    if (!TryReadU32(uc, self + kOffPoolA, &t->poolA)) return false;
+    if (!TryReadU32(uc, self + kOffPoolB, &t->poolB)) return false;
+    if (!TryReadU32(uc, self + kOffPoolThreshold, &t->threshold)) return false;
+    uint64_t total = (uint64_t)t->countA + t->countB;
+    return total != 0 && total <= kMaxEntries;
+}
+
+bool BuildIndex(uc_engine* uc, uint32_t self, TableCache* t) {
+    TableCache desc;
+    if (!ReadTableDesc(uc, self, &desc)) return false;
+    desc.byName.reserve((size_t)(desc.countA + desc.countB) * 2);
+
+    const uint32_t total = desc.countA + desc.countB;
+    for (uint32_t i = 0; i < total; i++) {
+        uint32_t nameAddr = 0;
+        if (!EntryNameAddr(uc, desc, i, &nameAddr)) return false;
+        std::string name;
+        if (!TryReadString(uc, nameAddr, &name)) return false;
+        if (name.empty()) continue;
+        // First occurrence wins - the guest loop returns on its first match.
+        desc.byName.emplace(std::move(name), (int32_t)i);
+    }
+    *t = std::move(desc);
+    g_builds.fetch_add(1, std::memory_order_relaxed);
+    return true;
+}
+
+} // namespace
+
+void HookCb(uc_engine* uc, uint64_t, uint32_t, void*) {
+    uint32_t self = 0, namePtr = 0;
+    uc_reg_read(uc, UC_ARM_REG_R0, &self);
+    uc_reg_read(uc, UC_ARM_REG_R1, &namePtr);
+    if (!self || !namePtr) return;
+
+    // If the guest's own hash cache is ever enabled, step aside - that path
+    // also WRITES into guest structures (it memoises), and reproducing that
+    // here would be guesswork.
+    uint8_t cacheFlag = 0;
+    if (uc_mem_read(uc, self + kOffCacheFlag, &cacheFlag, 1) != UC_ERR_OK) return;
+    if (cacheFlag) return;
+
+    std::string query;
+    if (!TryReadString(uc, namePtr, &query) || query.empty()) return;
+
+    int32_t candidate = -1;
+    {
+        std::lock_guard<std::mutex> lock(g_mutex);
+        TableCache& cache = g_tables[self];
+
+        // The first attempt keyed the cache on the table ADDRESS and treated
+        // a changed entry count as "the table grew". The live log disproved
+        // that: one address alternated between 35 and 59 entries, i.e.
+        // DIFFERENT objects reusing the same address. So the descriptor is
+        // re-read every call (seven cheap word reads) and the index is
+        // rebuilt whenever any of it moved.
+        TableCache desc;
+        if (!ReadTableDesc(uc, self, &desc)) return;
+        const bool stale = cache.byName.empty() || cache.countA != desc.countA ||
+                           cache.countB != desc.countB || cache.entriesA != desc.entriesA ||
+                           cache.entriesB != desc.entriesB || cache.poolA != desc.poolA ||
+                           cache.poolB != desc.poolB || cache.threshold != desc.threshold;
+        if (stale && !BuildIndex(uc, self, &cache)) {
+            g_tables.erase(self);
+            return; // could not index safely - let the guest do its own scan
+        }
+
+        auto it = cache.byName.find(query);
+        if (it == cache.byName.end()) {
+            // Not found is NOT answered from cache: a stale index would turn
+            // a real entry into a false "absent", and absence is exactly what
+            // the caller acts on. Let the guest's own scan decide.
+            g_fellThrough.fetch_add(1, std::memory_order_relaxed);
+            return;
+        }
+        candidate = it->second;
+
+        // Verify the hit against live guest memory before trusting it. This
+        // is what makes a wrong structural assumption cost performance
+        // instead of correctness.
+        uint32_t nameAddr = 0;
+        std::string actual;
+        if (!EntryNameAddr(uc, cache, (uint32_t)candidate, &nameAddr) ||
+            !TryReadString(uc, nameAddr, &actual) || actual != query) {
+            g_tables.erase(self);
+            g_fellThrough.fetch_add(1, std::memory_order_relaxed);
+            return;
+        }
+    }
+
+    uint64_t n = g_served.fetch_add(1, std::memory_order_relaxed) + 1;
+    if (n % 200000 == 0) {
+        Log("name_lookup_accel: %llu lookups served natively, %llu fell through to the guest, "
+            "%llu index builds",
+            (unsigned long long)n,
+            (unsigned long long)g_fellThrough.load(std::memory_order_relaxed),
+            (unsigned long long)g_builds.load(std::memory_order_relaxed));
+    }
+
+    uint32_t lr = 0, ret = (uint32_t)candidate;
+    uc_reg_read(uc, UC_ARM_REG_LR, &lr);
+    uc_reg_write(uc, UC_ARM_REG_R0, &ret);
+    uc_reg_write(uc, UC_ARM_REG_PC, &lr);
+    uc_emu_stop(uc);
+}
+
+} // namespace name_lookup_accel

mpcore/src/main/cpp/emu/name_lookup_accel.h

@@ -0,0 +1,45 @@
+#pragma once
+
+#include <unicorn/unicorn.h>
+
+// Native acceleration for the game's "find resource index by name" lookup
+// (guest sub_4F3704), measured by the block profiler as 18.8% of all
+// load-time samples - the second hottest thing after zlib's crc32.
+//
+// Why it is so expensive, from a live probe rather than from reading the
+// code: the function HAS a hash-map fast path with memoisation, but both
+// halves are gated on a byte at *(self+8), and that byte is **0** in this
+// build - so the cache is simply never used and every call falls through to
+// a LINEAR scan doing strcmp against a 6232-entry name table. Measured
+// 320,000+ calls in ~40 seconds, i.e. on the order of a billion emulated
+// strcmp comparisons. The names seen are shader/material parameters
+// ("AmbientR", "LightingIndex", "LateralSlices", "Z"), which is why this
+// hurts frame time as well as load time - they are resolved per object.
+//
+// Real hardware runs the same disabled-cache code and absorbs it; at ~12.8M
+// emulated instructions/sec this layer cannot.
+//
+// Approach: keep the guest's data structures untouched and answer the lookup
+// from a host-side hash map built once per table (rebuilt if the table's own
+// entry counts change). Same interception mechanism as zlib_accel and
+// FnvHashAccelHookCb - UC_HOOK_CODE at the entry, PC=LR, uc_emu_stop.
+//
+// Guest layout, read straight out of the decompile:
+//   *(self+8)    byte  - cache-enabled flag (0 here; if ever non-zero this
+//                        layer steps aside and lets the guest run its own
+//                        cached path)
+//   *(self+196)  ptr   - first entry array, 8 bytes per entry {offset, len}
+//   *(self+200)  u32   - number of entries in the first array
+//   *(self+204)  ptr   - second entry array, same element layout
+//   *(self+220)  u32   - number of entries in the second array
+//   *(self+224)  ptr   - string pool A
+//   *(self+228)  u32   - offset threshold selecting pool A vs B
+//   *(self+232)  ptr   - string pool B
+// Return value: the entry index, or -1 when the name is absent.
+namespace name_lookup_accel {
+
+constexpr uint64_t kLookupAddr = 0x4f3704;
+
+void HookCb(uc_engine* uc, uint64_t address, uint32_t size, void* userData);
+
+} // namespace name_lookup_accel

mpcore/src/main/cpp/emu/ostream_repro_test.cpp

@@ -0,0 +1,170 @@
+#include "ostream_repro_test.h"
+#include "guest_engine.h"
+
+#include <android/log.h>
+#include <cstring>
+#include <cstdint>
+
+namespace {
+
+// Real device path the artifact gets pushed to ahead of time (see
+// ostream_repro/build.sh's own instructions and this session's
+// ARM64_TRANSLATION_LAYER.md entry for the exact adb invocation used) -
+// this app's own internal files dir, the same directory
+// GameActivityMain.kt's loadEmulatedLibappFromAssets() extracts the real
+// libapp.so asset into (`filesDir`), just for a file this project's build
+// never bundles as an asset itself since it's a throwaway diagnostic, not a
+// real dependency of the app.
+constexpr const char* kOstreamReproPath = "/data/data/com.ea.games.nfs13_arm/files/ostream_repro.so";
+constexpr const char* kEntrySymbol = "TestOstreamAssembly";
+
+// MUST match ostream_repro.cpp's own four separate operator<< writes
+// exactly - this is the host-side oracle this test checks the guest's
+// extracted string against.
+constexpr const char* kExpected =
+    "//FRAGMENT SHADER\n"
+    "//===========\n\n"
+    "void main()\n{\n"
+    "}\n";
+
+constexpr uint32_t kResultBufSize = 260; // 4 (int32 length) + up to 256 bytes of content
+
+} // namespace
+
+void RunOstreamAssemblyReproTest(GuestEngine& engine) {
+    GuestAddr entry = engine.LoadSecondaryImage(kOstreamReproPath, kEntrySymbol);
+    if (!entry) {
+        __android_log_print(ANDROID_LOG_INFO, "OSTREAM_REPRO",
+            "RunOstreamAssemblyReproTest: LoadSecondaryImage(%s) failed or the entry symbol "
+            "wasn't found - see the preceding GuestEngine log line for which. Skipping (not "
+            "fatal - this artifact is a throwaway diagnostic, not a real app dependency); push "
+            "it via ostream_repro/build.sh + adb if you want this test to actually run.",
+            kOstreamReproPath);
+        return;
+    }
+
+    GuestAddr resultBuf = engine.AllocPermanent(kResultBufSize);
+    if (!resultBuf) {
+        __android_log_print(ANDROID_LOG_INFO, "OSTREAM_REPRO",
+            "RunOstreamAssemblyReproTest: AllocPermanent(%u) for the result buffer failed",
+            kResultBufSize);
+        return;
+    }
+
+    // TestOstreamAssembly(char* outBuf, int outBufSize) - AAPCS32 r0/r1,
+    // matches the convenience 2-arg CallGuestFunction overload exactly.
+    uint32_t retVal = engine.CallGuestFunction(entry, resultBuf, kResultBufSize);
+
+    int32_t reportedLen = 0;
+    memcpy(&reportedLen, engine.G2H(resultBuf), sizeof(reportedLen));
+    int copyLen = reportedLen;
+    if (copyLen < 0) copyLen = 0;
+    if (copyLen > (int)(kResultBufSize - 4)) copyLen = (int)(kResultBufSize - 4);
+    char content[kResultBufSize - 4 + 1] = {0};
+    memcpy(content, (const char*)engine.G2H(resultBuf) + 4, (size_t)copyLen);
+    content[copyLen] = 0;
+
+    size_t expectedLen = strlen(kExpected);
+    bool lengthMatches = (reportedLen == (int32_t)expectedLen);
+    bool contentMatches = lengthMatches && (memcmp(content, kExpected, expectedLen) == 0);
+
+    if (contentMatches) {
+        __android_log_print(ANDROID_LOG_INFO, "OSTREAM_REPRO",
+            "RunOstreamAssemblyReproTest: PASS - extracted std::ostringstream content matches "
+            "exactly what was written (len=%d, retVal=%u). The isolated write-then-extract "
+            "pattern works correctly under GuestEngine in total isolation from libapp.so - "
+            "whatever breaks the real game's sub_4702D8/sub_27160C path is NOT a general "
+            "ostringstream/basic_stringbuf-extraction bug in this engine.",
+            reportedLen, retVal);
+    } else if (reportedLen == 0) {
+        __android_log_print(ANDROID_LOG_INFO, "OSTREAM_REPRO",
+            "RunOstreamAssemblyReproTest: FAIL (REPRODUCES the real-game symptom) - extraction "
+            "came back EMPTY (len=0, retVal=%u) despite writing %zu bytes of real content via "
+            "4 separate operator<< calls, in total isolation from libapp.so. This is the SAME "
+            "'write succeeds, extraction returns empty' symptom already traced through the real "
+            "game's own sub_4702D8/sub_27160C - reproducing it here, in a minimal standalone "
+            "artifact with no game code involved at all, is real evidence this is a general "
+            "std::ostringstream/basic_stringbuf<char>::str()-extraction correctness bug in "
+            "GuestEngine itself, not something specific to libapp.so's own state.",
+            retVal, expectedLen);
+    } else {
+        __android_log_print(ANDROID_LOG_INFO, "OSTREAM_REPRO",
+            "RunOstreamAssemblyReproTest: FAIL (different from the real-game symptom) - "
+            "extracted len=%d (expected %zu), retVal=%u, content=\"%s\" - non-empty but WRONG "
+            "content is a different failure mode than the real game's clean empty-string "
+            "symptom; inspect `content` above before drawing a conclusion either way.",
+            reportedLen, expectedLen, retVal, content);
+    }
+}
+
+namespace {
+constexpr const char* kNestedEntrySymbol = "TestOstreamAssemblyNested";
+// MUST match ostream_repro.cpp's own TestOstreamAssemblyNested exactly.
+constexpr const char* kNestedExpected =
+    "//VERTEX SHADER\n//=============\n\n"
+    "//Attributes\n//==========\n";
+} // namespace
+
+// 2026-09-17, ARM64_TRANSLATION_LAYER.md - the 0x3d3d3d3d heap-overflow
+// chase. Reuses the same LoadSecondaryImage/CallGuestFunction plumbing as
+// RunOstreamAssemblyReproTest above, against ostream_repro.cpp's NEW
+// TestOstreamAssemblyNested export - the FIRST write alone (33 bytes)
+// already forces libc++'s SSO->heap transition, immediately followed by a
+// REAL function-call boundary (WriteAttributesSectionNested, noinline) that
+// writes MORE content into the SAME shared stream - the exact shape of
+// sub_46FD58 -> sub_4711C8's own real call, in total isolation from every
+// other line of game code. If this ALSO corrupts/misbehaves under
+// GuestEngine, that's decisive: the bug is in this engine's own handling of
+// "grow past SSO on the first write, then write again across a function
+// call boundary" - not something specific to the real game's broader state.
+void RunOstreamAssemblyNestedReproTest(GuestEngine& engine) {
+    GuestAddr entry = engine.LoadSecondaryImage(kOstreamReproPath, kNestedEntrySymbol);
+    if (!entry) {
+        __android_log_print(ANDROID_LOG_INFO, "OSTREAM_REPRO",
+            "RunOstreamAssemblyNestedReproTest: LoadSecondaryImage(%s, %s) failed - see the "
+            "preceding GuestEngine log line for why. Push a freshly-rebuilt ostream_repro.so "
+            "if this is unexpected.",
+            kOstreamReproPath, kNestedEntrySymbol);
+        return;
+    }
+
+    GuestAddr resultBuf = engine.AllocPermanent(kResultBufSize);
+    if (!resultBuf) {
+        __android_log_print(ANDROID_LOG_INFO, "OSTREAM_REPRO",
+            "RunOstreamAssemblyNestedReproTest: AllocPermanent(%u) for the result buffer failed",
+            kResultBufSize);
+        return;
+    }
+
+    uint32_t retVal = engine.CallGuestFunction(entry, resultBuf, kResultBufSize);
+
+    int32_t reportedLen = 0;
+    memcpy(&reportedLen, engine.G2H(resultBuf), sizeof(reportedLen));
+    int copyLen = reportedLen;
+    if (copyLen < 0) copyLen = 0;
+    if (copyLen > (int)(kResultBufSize - 4)) copyLen = (int)(kResultBufSize - 4);
+    char content[kResultBufSize - 4 + 1] = {0};
+    memcpy(content, (const char*)engine.G2H(resultBuf) + 4, (size_t)copyLen);
+    content[copyLen] = 0;
+
+    size_t expectedLen = strlen(kNestedExpected);
+    bool lengthMatches = (reportedLen == (int32_t)expectedLen);
+    bool contentMatches = lengthMatches && (memcmp(content, kNestedExpected, expectedLen) == 0);
+
+    if (contentMatches) {
+        __android_log_print(ANDROID_LOG_INFO, "OSTREAM_REPRO",
+            "RunOstreamAssemblyNestedReproTest: PASS - len=%d retVal=%u matches exactly. The "
+            "'long first write forcing SSO->heap, then a nested function call writing more into "
+            "the same stream' pattern works correctly in total isolation - the real crash's bug "
+            "is NOT reproduced by this shape alone, so something ELSE about the real game's "
+            "broader state/heap layout at that moment is implicated instead.",
+            reportedLen, retVal);
+    } else {
+        __android_log_print(ANDROID_LOG_INFO, "OSTREAM_REPRO",
+            "RunOstreamAssemblyNestedReproTest: FAIL - len=%d (expected %zu) retVal=%u "
+            "content=\"%s\" - THIS ISOLATED SHAPE ALONE reproduces a problem, independent of "
+            "the real game's own state - strong evidence the bug is in GuestEngine's general "
+            "handling of this exact call pattern, not something libapp.so-specific.",
+            reportedLen, expectedLen, retVal, content);
+    }
+}

mpcore/src/main/cpp/emu/ostream_repro_test.h

@@ -0,0 +1,38 @@
+#pragma once
+
+class GuestEngine;
+
+// 2026-09-16, ARM64_TRANSLATION_LAYER.md - "isolated std::ostringstream
+// repro" test. Loads a SEPARATE, tiny, independently-compiled armeabi-v7a
+// artifact (../../../ostream_repro/ostream_repro.cpp, built via
+// ostream_repro/build.sh, pushed to the device ahead of time - NOT part of
+// this Gradle build, see that file's own comments) via
+// GuestEngine::LoadSecondaryImage, then calls its one exported entry point
+// (TestOstreamAssembly) and logs whether the write-then-extract
+// std::ostringstream pattern this artifact exercises comes back correct or
+// empty - the same symptom this session spent most of 2026-09-16 tracing
+// through the real game's own sub_4702D8/sub_27160C, but here in total
+// isolation from every other line of game code. Per the user's own explicit
+// direction ("ты сейчас пытаешься подогнать эмуляцию к одному единственному
+// бинарнику, это не правильный подход"), this is what actually answers
+// "is this a general bug in GuestEngine, or something specific to
+// libapp.so's own state" - continuing to probe more hardcoded libapp.so
+// addresses could not have answered that question no matter how far it
+// went.
+//
+// Logs its own PASS/FAIL verdict unambiguously (tag "OSTREAM_REPRO") -
+// see ostream_repro_test.cpp's own top comment for exactly what counts as
+// each. No-ops (logs and returns) if the secondary image fails to load -
+// e.g. the artifact was never pushed to this device - so this is safe to
+// leave wired into LoadEmulatedLibapp without risking the real game's own
+// boot sequence if the file is simply missing.
+void RunOstreamAssemblyReproTest(GuestEngine& engine);
+
+// 2026-09-17, ARM64_TRANSLATION_LAYER.md - the 0x3d3d3d3d heap-overflow
+// chase. Same idea as above, against ostream_repro.cpp's
+// TestOstreamAssemblyNested export instead - a long first write forcing an
+// immediate SSO->heap transition, then a real (noinline) function-call
+// boundary writing more into the same shared stream, matching
+// sub_46FD58->sub_4711C8's own shape. See ostream_repro_test.cpp's own
+// comment for the full rationale.
+void RunOstreamAssemblyNestedReproTest(GuestEngine& engine);

mpcore/src/main/cpp/emu/profiler.cpp

@@ -0,0 +1,67 @@
+#include "profiler.h"
+#include "../util/util.h"
+#include <atomic>
+#include <mutex>
+#include <unordered_map>
+#include <vector>
+#include <algorithm>
+#include <chrono>
+#include <thread>
+
+namespace {
+
+std::atomic<bool> g_profilingEnabled{false};
+std::mutex g_histMutex;
+std::unordered_map<uint64_t, uint64_t> g_hist;
+std::atomic<uint64_t> g_totalSamples{0};
+std::atomic<bool> g_dumpThreadStarted{false};
+
+} // namespace
+
+void EnableProfiling() { g_profilingEnabled.store(true, std::memory_order_relaxed); }
+bool ProfilingEnabled() { return g_profilingEnabled.load(std::memory_order_relaxed); }
+
+void ProfileBlockHookCb(uc_engine*, uint64_t address, uint32_t, void*) {
+    // thread_local, not a shared "last sample" - each real host thread has
+    // its own uc_engine (see guest_engine.h's "Multithreading model") and
+    // fires this independently; gating per-thread avoids one busy thread's
+    // sampling starving another's.
+    static thread_local std::chrono::steady_clock::time_point lastSample{};
+    auto now = std::chrono::steady_clock::now();
+    if (now - lastSample < std::chrono::milliseconds(2)) return;
+    lastSample = now;
+
+    std::lock_guard<std::mutex> lock(g_histMutex);
+    g_hist[address]++;
+    g_totalSamples.fetch_add(1, std::memory_order_relaxed);
+}
+
+void StartProfileDumpThread() {
+    bool expected = false;
+    if (!g_dumpThreadStarted.compare_exchange_strong(expected, true)) return; // already running
+
+    std::thread([]() {
+        while (true) {
+            std::this_thread::sleep_for(std::chrono::seconds(3));
+
+            std::vector<std::pair<uint64_t, uint64_t>> top;
+            {
+                std::lock_guard<std::mutex> lock(g_histMutex);
+                top.assign(g_hist.begin(), g_hist.end());
+            }
+            if (top.empty()) continue;
+
+            std::sort(top.begin(), top.end(),
+                      [](const auto& a, const auto& b) { return a.second > b.second; });
+            uint64_t total = g_totalSamples.load(std::memory_order_relaxed);
+
+            Log("PROFILE: %llu total samples across %zu distinct block addresses - top hot PCs:",
+                (unsigned long long)total, top.size());
+            for (size_t i = 0; i < top.size() && i < 15; i++) {
+                Log("PROFILE:   0x%llx - %llu samples (%.1f%%)",
+                    (unsigned long long)top[i].first, (unsigned long long)top[i].second,
+                    total ? 100.0 * (double)top[i].second / (double)total : 0.0);
+            }
+        }
+    }).detach();
+}

mpcore/src/main/cpp/emu/profiler.h

@@ -0,0 +1,29 @@
+#pragma once
+
+#include <unicorn/unicorn.h>
+
+// Throwaway sampling profiler for the "why did onCreate take 115 seconds"
+// investigation (see ARM64_TRANSLATION_LAYER.md, 2026-09-01 entry) - NOT a
+// permanent part of the architecture, just the cheapest way to answer "where
+// does the guest CPU actually spend its time" without a real disassembler-
+// aware profiler. No-op unless EnableProfiling() is called (see main.cpp).
+//
+// Mechanism: a UC_HOOK_BLOCK callback (fires once per translated basic
+// block, not per instruction - much cheaper) installed on every guest
+// engine (see GuestEngine::EnsureThreadEngine) across the loaded image's own
+// code range. Time-gated per-thread sampling (skips most block hits, only
+// records roughly every 2ms of wall-clock time) keeps overhead from
+// dominating the very thing being measured. A background thread dumps the
+// hottest sampled PCs to logcat every few seconds - cross-reference those
+// addresses against the IDA database (native_lib/libapp.so.i64, guest
+// addresses ARE real file vaddrs - see guest_engine.h's own class comment on
+// why bias is always 0) to find which real functions are hot.
+void EnableProfiling();
+bool ProfilingEnabled();
+
+// UC_HOOK_BLOCK callback - pass directly to uc_hook_add.
+void ProfileBlockHookCb(uc_engine* uc, uint64_t address, uint32_t size, void* user_data);
+
+// Starts (once) a detached background thread that logs the top hottest
+// sampled PCs every 3 seconds until the process exits.
+void StartProfileDumpThread();

mpcore/src/main/cpp/emu/pthread_shim.cpp

@@ -0,0 +1,312 @@
+#include "pthread_shim.h"
+#include "../util/util.h"
+#include <thread>
+#include <mutex>
+#include <condition_variable>
+#include <chrono>
+#include <unordered_map>
+#include <cstring>
+#include <ctime>
+
+namespace {
+
+// ---- Guest pthread_t handle table ----
+// Real bionic pthread_t values are host-thread-implementation-specific and
+// never exposed to guest code - guest code only ever receives an opaque
+// uint32_t handle from Shim_pthread_create and only ever passes it back into
+// Shim_pthread_join, so this encoding is a private contract of this file,
+// not a real bionic ABI.
+struct GuestThreadRecord {
+    std::thread thread;
+};
+std::mutex g_threadsMutex;
+std::unordered_map<uint32_t, GuestThreadRecord*> g_threads;
+uint32_t g_nextThreadHandle = 1;
+
+uint32_t Shim_pthread_create(GuestEngine& eng, uint32_t threadOutPtr, uint32_t /*attr*/,
+                              uint32_t startRoutine, uint32_t arg, uint32_t) {
+    if (!startRoutine) {
+        Log("pthread_shim: pthread_create with null start_routine");
+        return -1;
+    }
+    // Diagnostic: log the REAL caller address (LR at the point this stub
+    // was entered - register state is still exactly as the hook fired with,
+    // since import_stub_dispatch_cb hasn't written anything back yet at
+    // this point) so a suspiciously-fast-returning thread's actual call
+    // site can be found in IDA, and whether startRoutine itself is real
+    // libapp.so code vs one of our own stub addresses (anything >=
+    // GuestEngine's own image_end() is a stub, not real code - see
+    // guest_engine.h's arena layout).
+    {
+        uint32_t lr = 0;
+        uc_reg_read(eng.uc(), UC_ARM_REG_LR, &lr);
+        Log("pthread_shim: pthread_create called from guest LR=0x%x, startRoutine=0x%x (image_end=0x%x)",
+            lr, startRoutine, eng.image_end());
+    }
+
+    // startRoutine must point into the real loaded image - anything else is
+    // not ARM32 code at all, it's one of this engine's own arena addresses
+    // (heap/trampoline/import-stub/misc-stub/control/thread-stacks all live
+    // past image_end()). Spawning a host thread that calls
+    // CallGuestFunction() on such an address doesn't fail cleanly - if it
+    // happens to land on one of this engine's own AllocCodeStub dispatch
+    // points, it invokes some unrelated real shim with whatever garbage sits
+    // in r1-r3 for a freshly-created, never-primed uc_engine, which was
+    // previously observed to cascade into a burst of unrelated shim calls
+    // with corrupted arguments and an eventual MEM FAULT at image_end_
+    // itself (see ARM64_TRANSLATION_LAYER.md, "register/stack corruption"
+    // investigation). Reject loudly and immediately instead - one clear
+    // diagnostic beats six confusing downstream ones.
+    //
+    // Corrected 2026-09-21 (task #67): this used to compare against
+    // image_end(), which was right only while exactly ONE image existed. Once
+    // the game's own libfmodex/libfmodevent load as sibling images - far above
+    // image_end() - that test rejected FMOD's OWN mixer thread as "not real
+    // image code". The refusal propagated all the way up as silence:
+    //
+    //   pthread_create -> EINVAL -> sub_A9120 -> 33 -> System::init -> 33
+    //     -> EventSystem::init -> 33 -> fmodGetInfo -> -1
+    //     -> FMODAudioDevice never builds its AudioTrack
+    //
+    // IsGuestImageCode knows about every loaded image, so the guard keeps its
+    // original purpose without the single-image assumption.
+    if (!eng.IsGuestImageCode(startRoutine)) {
+        Log("pthread_shim: REFUSING pthread_create - startRoutine=0x%x is not inside any loaded "
+            "guest image (%s)", startRoutine, eng.DescribeAddress(startRoutine).c_str());
+        return 22; // EINVAL - matches pthread_create's own errno-style failure contract
+    }
+
+    uint32_t handle;
+    {
+        std::lock_guard<std::mutex> lock(g_threadsMutex);
+        handle = g_nextThreadHandle++;
+    }
+
+    auto* record = new GuestThreadRecord();
+    // `eng` is always GuestEngine::Instance() (a static singleton, see
+    // ImportShimFn's contract) - safe to capture by reference into a thread
+    // that outlives this call.
+    record->thread = std::thread([&eng, startRoutine, arg, handle]() {
+        // Every new host thread needs its OWN uc_engine before it can touch
+        // any guest register - see guest_engine.h's "Multithreading model".
+        eng.EnsureThreadEngine();
+        uint32_t result = eng.CallGuestFunction(startRoutine, arg);
+        Log("pthread_shim: guest thread (handle %u) start_routine returned 0x%x", handle, result);
+        // Hand this thread's guest stack(s) and uc_engine back. Without this
+        // the thread-stack arena was one-way: the game creates threads across
+        // a session (one per race, among others) and after kMaxGuestThreads of
+        // them CarveThreadStack started returning 0, the next thread's start
+        // routine never ran, and the race came up as a black screen.
+        eng.ReleaseThreadEngine();
+    });
+
+    {
+        std::lock_guard<std::mutex> lock(g_threadsMutex);
+        g_threads[handle] = record;
+    }
+
+    if (threadOutPtr) memcpy(eng.G2H(threadOutPtr), &handle, sizeof(handle));
+    Log("pthread_shim: pthread_create -> guest handle %u, start_routine=0x%x, arg=0x%x",
+        handle, startRoutine, arg);
+    return 0;
+}
+
+uint32_t Shim_pthread_join(GuestEngine& eng, uint32_t handle, uint32_t retvalOutPtr, uint32_t, uint32_t, uint32_t) {
+    GuestThreadRecord* record = nullptr;
+    {
+        std::lock_guard<std::mutex> lock(g_threadsMutex);
+        auto it = g_threads.find(handle);
+        if (it != g_threads.end()) record = it->second;
+    }
+    if (!record) {
+        Log("pthread_shim: pthread_join(%u) - unknown handle", handle);
+        return 3; // ESRCH
+    }
+    if (record->thread.joinable()) record->thread.join();
+    // The guest start_routine's real void* return value isn't propagated
+    // here (see pthread_shim.h's own gap list) - writing 0 is the closest
+    // correct-shaped stand-in for callers that check *retval for NULL.
+    if (retvalOutPtr) {
+        uint32_t zero = 0;
+        memcpy(eng.G2H(retvalOutPtr), &zero, sizeof(zero));
+    }
+    {
+        std::lock_guard<std::mutex> lock(g_threadsMutex);
+        g_threads.erase(handle);
+    }
+    delete record;
+    return 0;
+}
+
+// ---- Mutexes ----
+// Keyed by the GUEST ADDRESS of the pthread_mutex_t object (stable for its
+// lifetime - always a field of some other guest struct or a guest global,
+// never moved). std::recursive_mutex (not std::mutex) regardless of the
+// real attr type requested - see pthread_shim.h's gap list for why.
+std::mutex g_mutexTableMutex;
+std::unordered_map<uint32_t, std::recursive_mutex*> g_mutexes;
+
+std::recursive_mutex* GetOrCreateMutex(uint32_t guestAddr) {
+    std::lock_guard<std::mutex> lock(g_mutexTableMutex);
+    auto it = g_mutexes.find(guestAddr);
+    if (it != g_mutexes.end()) return it->second;
+    auto* m = new std::recursive_mutex();
+    g_mutexes[guestAddr] = m;
+    return m;
+}
+
+uint32_t Shim_pthread_mutex_init(GuestEngine&, uint32_t mutexPtr, uint32_t /*attr*/, uint32_t, uint32_t, uint32_t) {
+    if (mutexPtr) GetOrCreateMutex(mutexPtr);
+    return 0;
+}
+uint32_t Shim_pthread_mutex_lock(GuestEngine&, uint32_t mutexPtr, uint32_t, uint32_t, uint32_t, uint32_t) {
+    if (!mutexPtr) return 22; // EINVAL
+    GetOrCreateMutex(mutexPtr)->lock();
+    return 0;
+}
+uint32_t Shim_pthread_mutex_unlock(GuestEngine&, uint32_t mutexPtr, uint32_t, uint32_t, uint32_t, uint32_t) {
+    if (!mutexPtr) return 22; // EINVAL
+    GetOrCreateMutex(mutexPtr)->unlock();
+    return 0;
+}
+uint32_t Shim_pthread_mutex_trylock(GuestEngine&, uint32_t mutexPtr, uint32_t, uint32_t, uint32_t, uint32_t) {
+    if (!mutexPtr) return 22; // EINVAL
+    return GetOrCreateMutex(mutexPtr)->try_lock() ? 0 : 16; // EBUSY
+}
+uint32_t Shim_pthread_mutex_destroy(GuestEngine&, uint32_t mutexPtr, uint32_t, uint32_t, uint32_t, uint32_t) {
+    std::lock_guard<std::mutex> lock(g_mutexTableMutex);
+    auto it = g_mutexes.find(mutexPtr);
+    if (it != g_mutexes.end()) {
+        delete it->second;
+        g_mutexes.erase(it);
+    }
+    return 0;
+}
+
+// ---- Condition variables ----
+// std::condition_variable_any (not std::condition_variable) specifically
+// because it's the variant that works with std::recursive_mutex - a plain
+// std::condition_variable only accepts std::unique_lock<std::mutex>.
+std::mutex g_condTableMutex;
+std::unordered_map<uint32_t, std::condition_variable_any*> g_conds;
+
+std::condition_variable_any* GetOrCreateCond(uint32_t guestAddr) {
+    std::lock_guard<std::mutex> lock(g_condTableMutex);
+    auto it = g_conds.find(guestAddr);
+    if (it != g_conds.end()) return it->second;
+    auto* cv = new std::condition_variable_any();
+    g_conds[guestAddr] = cv;
+    return cv;
+}
+
+uint32_t Shim_pthread_cond_init(GuestEngine&, uint32_t condPtr, uint32_t, uint32_t, uint32_t, uint32_t) {
+    if (condPtr) GetOrCreateCond(condPtr);
+    return 0;
+}
+uint32_t Shim_pthread_cond_destroy(GuestEngine&, uint32_t condPtr, uint32_t, uint32_t, uint32_t, uint32_t) {
+    std::lock_guard<std::mutex> lock(g_condTableMutex);
+    auto it = g_conds.find(condPtr);
+    if (it != g_conds.end()) {
+        delete it->second;
+        g_conds.erase(it);
+    }
+    return 0;
+}
+// TEMP diagnostic for the render-stall investigation (see
+// ARM64_TRANSLATION_LAYER.md's "pthread_cond_wait deadlock" plan) - logs the
+// real guest caller (LR, same technique Shim_pthread_create already uses)
+// and the condvar's guest address, so a hang can be traced to the exact
+// calling function in IDA instead of guessed at.
+uint32_t GuestCallerLR(GuestEngine& eng) {
+    uint32_t lr = 0;
+    uc_reg_read(eng.uc(), UC_ARM_REG_LR, &lr);
+    return lr;
+}
+
+// Diagnostic tracing for the condvar shims (task #7's deadlock hunt). OFF by
+// default since 2026-09-19: signal alone fired 20,085 times in one
+// prologue-load capture, and every one of these lines is a blocking write to
+// logd on a path the engine takes constantly. Flip to true for a targeted
+// deadlock capture, not for normal runs.
+constexpr bool kTraceCondVars = false;
+
+uint32_t Shim_pthread_cond_signal(GuestEngine& eng, uint32_t condPtr, uint32_t, uint32_t, uint32_t, uint32_t) {
+    if (kTraceCondVars)
+        Log("pthread_shim: pthread_cond_signal(cond=0x%x) from guest LR=0x%x", condPtr, GuestCallerLR(eng));
+    if (condPtr) GetOrCreateCond(condPtr)->notify_one();
+    return 0;
+}
+uint32_t Shim_pthread_cond_broadcast(GuestEngine& eng, uint32_t condPtr, uint32_t, uint32_t, uint32_t, uint32_t) {
+    Log("pthread_shim: pthread_cond_broadcast(cond=0x%x) from guest LR=0x%x", condPtr, GuestCallerLR(eng));
+    if (condPtr) GetOrCreateCond(condPtr)->notify_all();
+    return 0;
+}
+
+// Real pthread_cond_wait semantics: mutexPtr is ALREADY locked (by this same
+// guest thread) on entry, must be atomically unlocked while waiting, and
+// re-locked before returning. std::condition_variable_any::wait(lock) wants
+// to manage a Lockable itself, so this adopts the ALREADY-held lock
+// (adopt_lock - no double-lock attempt), waits (which correctly unlocks/
+// relocks around the real OS wait), then release()s the unique_lock's
+// ownership WITHOUT unlocking, since the real mutex must stay locked for the
+// caller on return - exactly matching real pthread_cond_wait's contract.
+uint32_t Shim_pthread_cond_wait(GuestEngine& eng, uint32_t condPtr, uint32_t mutexPtr, uint32_t, uint32_t, uint32_t) {
+    if (!condPtr || !mutexPtr) return 22; // EINVAL
+    Log("pthread_shim: pthread_cond_wait(cond=0x%x, mutex=0x%x) from guest LR=0x%x - blocking now",
+        condPtr, mutexPtr, GuestCallerLR(eng));
+    auto* cv = GetOrCreateCond(condPtr);
+    auto* mtx = GetOrCreateMutex(mutexPtr);
+    std::unique_lock<std::recursive_mutex> lock(*mtx, std::adopt_lock);
+    cv->wait(lock);
+    lock.release();
+    Log("pthread_shim: pthread_cond_wait(cond=0x%x) woke up", condPtr);
+    return 0;
+}
+
+uint32_t Shim_pthread_cond_timedwait(GuestEngine& eng, uint32_t condPtr, uint32_t mutexPtr,
+                                      uint32_t abstimePtr, uint32_t, uint32_t) {
+    if (!condPtr || !mutexPtr) return 22; // EINVAL
+    auto* cv = GetOrCreateCond(condPtr);
+    auto* mtx = GetOrCreateMutex(mutexPtr);
+    std::unique_lock<std::recursive_mutex> lock(*mtx, std::adopt_lock);
+
+    std::cv_status status = std::cv_status::no_timeout;
+    if (abstimePtr) {
+        // Guest struct timespec { long tv_sec; long tv_nsec; } - both
+        // 32-bit fields on this ABI, 8 bytes total, same layout host-side.
+        uint32_t sec = 0, nsec = 0;
+        memcpy(&sec, eng.G2H(abstimePtr), 4);
+        memcpy(&nsec, eng.G2H(abstimePtr + 4), 4);
+        // abstime is CLOCK_REALTIME-based unless the guest called
+        // pthread_condattr_setclock first (not observed at any call site) -
+        // std::chrono::system_clock is the closest host equivalent.
+        auto deadline = std::chrono::system_clock::from_time_t((time_t)sec) +
+                         std::chrono::nanoseconds(nsec);
+        status = cv->wait_until(lock, deadline);
+    } else {
+        cv->wait(lock);
+    }
+
+    lock.release();
+    return status == std::cv_status::timeout ? 110 : 0; // ETIMEDOUT
+}
+
+} // namespace
+
+void RegisterPthreadImportShims(GuestEngine& engine) {
+    engine.RegisterImportShim("pthread_create", Shim_pthread_create);
+    engine.RegisterImportShim("pthread_join", Shim_pthread_join);
+
+    engine.RegisterImportShim("pthread_mutex_init", Shim_pthread_mutex_init);
+    engine.RegisterImportShim("pthread_mutex_lock", Shim_pthread_mutex_lock);
+    engine.RegisterImportShim("pthread_mutex_unlock", Shim_pthread_mutex_unlock);
+    engine.RegisterImportShim("pthread_mutex_trylock", Shim_pthread_mutex_trylock);
+    engine.RegisterImportShim("pthread_mutex_destroy", Shim_pthread_mutex_destroy);
+
+    engine.RegisterImportShim("pthread_cond_init", Shim_pthread_cond_init);
+    engine.RegisterImportShim("pthread_cond_destroy", Shim_pthread_cond_destroy);
+    engine.RegisterImportShim("pthread_cond_signal", Shim_pthread_cond_signal);
+    engine.RegisterImportShim("pthread_cond_broadcast", Shim_pthread_cond_broadcast);
+    engine.RegisterImportShim("pthread_cond_wait", Shim_pthread_cond_wait);
+    engine.RegisterImportShim("pthread_cond_timedwait", Shim_pthread_cond_timedwait);
+}

mpcore/src/main/cpp/emu/pthread_shim.h

@@ -0,0 +1,38 @@
+#pragma once
+
+#include "guest_engine.h"
+
+// Real pthread threading support - replaces the old single-threaded no-op
+// fakes (see import_shims.cpp's own top comment for what those used to be).
+// pthread_create spawns a genuine host std::thread that calls
+// GuestEngine::EnsureThreadEngine() (its own uc_engine sharing the same
+// guest memory - see guest_engine.h's "Multithreading model") before running
+// the guest start_routine; pthread_mutex_t/pthread_cond_t are backed by real
+// std::recursive_mutex/std::condition_variable_any objects, keyed by the
+// GUEST ADDRESS of the pthread_mutex_t/pthread_cond_t object itself (stable
+// for the object's lifetime - these are always fields of some other guest
+// struct or globals, never moved).
+//
+// Known gaps (documented, not silently wrong):
+// - pthread_attr_t is entirely ignored (detached-vs-joinable, stack size,
+//   scheduling priority) - every guest thread is created host-joinable
+//   regardless of what the guest requested; pthread_join is the only exit
+//   path this shim supports (a guest thread created "detached" that's never
+//   joined will leak its host std::thread object, same as an ordinary
+//   pthread_join call the caller forgets to make - acceptable for a
+//   prototype scope).
+// - pthread_exit() is NOT implemented (falls through to the generic
+//   "unresolved import, return 0" handler) - a guest thread that calls it
+//   explicitly (rather than just returning from its start_routine, the
+//   common case) will incorrectly resume as if it were an ordinary no-op
+//   call rather than unwinding. Fixing this properly needs
+//   import_stub_dispatch_cb itself (guest_engine.cpp) to let a shim
+//   override the unconditional "write PC=lr" return path, which no other
+//   shim currently needs - deferred.
+// - std::recursive_mutex (not std::mutex) backs every guest mutex
+//   regardless of the real attr type requested, specifically so a
+//   PTHREAD_MUTEX_RECURSIVE guest mutex (common in game engines) can't
+//   self-deadlock against a plain std::mutex that doesn't support it - a
+//   deliberately safe default, not a precise recursive/non-recursive
+//   distinction.
+void RegisterPthreadImportShims(GuestEngine& engine);

mpcore/src/main/cpp/emu/rtti_shims.h

@@ -0,0 +1,63 @@
+#pragma once
+
+#include "guest_engine.h"
+
+// Real RTTI (typeid/dynamic_cast) and minimal C++ exception-class support
+// for the imports libc++abi/libc++ would normally provide (not statically
+// linked into libapp.so - these came up UNDEFINED same as every other gap
+// this session has been closing, see ARM64_TRANSLATION_LAYER.md's "go
+// through all the imports" entry).
+//
+// Two distinct pieces, because these symbols are a mix of DATA and CODE:
+//
+// SetupRttiDataSymbols(engine) - a GuestEngine::DataSymbolSetupFn (register
+// via engine.RegisterDataSymbolSetup BEFORE engine.LoadImage) - builds real,
+// permanently-allocated (see GuestEngine::AllocPermanent) type_info objects
+// for the 5 primitive types actually referenced (_ZTIa/_ZTIf/_ZTIi/_ZTIs/
+// _ZTIt - char/float/int/short/unsigned short) plus small "vtable identity"
+// marker blobs for the 5 __cxxabiv1 abstract RTTI base classes
+// (__class_type_info/__si_class_type_info/__vmi_class_type_info/
+// __pointer_type_info/__function_type_info). These markers are NOT real
+// vtables with real function pointers - RegisterRttiImportShims's own
+// __dynamic_cast implementation recognizes them by ADDRESS (matching how
+// the Itanium ABI's __dynamic_cast already distinguishes a type_info's
+// concrete kind by comparing its vtable pointer against known base-class
+// vtable addresses, not by making a virtual call) and interprets the
+// following fields directly, so no real virtual dispatch through these
+// markers is ever needed. Getting these resolved as real DATA (not a
+// callable code stub - see GuestEngine::RegisterDataSymbol's own comment)
+// depended on this session's ELF-relocation-addend fix (guest_engine.cpp's
+// ProcessRelocations) - a type_info object's own stored vtable-pointer
+// field is laid out at compile time as "vtable_symbol + 2*sizeof(void*)"
+// (the Itanium ABI's offset-to-top/rtti-slot skip), which is exactly the
+// non-zero implicit addend that fix started honoring.
+//
+// RegisterRttiImportShims(engine) - the callable pieces: a real
+// __dynamic_cast (walks the type_info hierarchy directly, not through
+// virtual dispatch - handles the common single/no-inheritance and
+// multiple-non-virtual-base cases; true virtual-inheritance diamonds are a
+// documented gap, not silently wrong), __cxa_bad_typeid (can't really
+// throw - see its own comment), minimal std::exception/logic_error/
+// runtime_error/bad_alloc constructor/destructor/what() (a simplified but
+// internally-consistent object layout - not byte-identical to real
+// libc++'s __libcpp_refstring-backed one, which is fine since libc++
+// itself was never statically linked here to compare against - only code
+// THIS file also wrote ever reads these bytes), std::uncaught_exception
+// (always false - no real exception is ever "in flight", see the
+// dedicated comment on why real throw/catch unwinding isn't attempted),
+// and a partial (refcount-only, no deleter-callback) __shared_weak_count
+// (std::shared_ptr's internal control block).
+//
+// Also covers the small "misc libc++ runtime" surface that came up
+// alongside RTTI in the same undefined-symbol sweep: std::cerr (a
+// generously-oversized inert data blob - real formatted-output support
+// would need libc++'s actual ostream/streambuf machinery, not attempted),
+// ios_base/locale's init/clear/destructor/getloc (safe no-ops/trivial
+// objects), the ctype<char>/num_get/num_put facet `id` statics (inert data
+// - nothing ever successfully resolves a facet lookup through them, see
+// use_facet's own comment for why), and libc++'s own internal std::mutex
+// (real - backed by the same real-mutex-table pattern pthread_shim.cpp
+// already uses for guest pthread_mutex_t, keyed by the object's own guest
+// address).
+void SetupRttiDataSymbols(GuestEngine& engine);
+void RegisterRttiImportShims(GuestEngine& engine);

mpcore/src/main/cpp/emu/tcg_bench.cpp

@@ -0,0 +1,511 @@
+#include "tcg_bench.h"
+#include "guest_engine.h"
+
+#include <unicorn/unicorn.h>
+#include <android/log.h>
+#include <chrono>
+#include <cstdint>
+#include <cstring>
+#include <vector>
+
+namespace {
+
+// ---- Minimal Thumb/Thumb-2 hand-assembler, just enough for the synthetic
+// engine tests below (2026-09-16, ARM64_TRANSLATION_LAYER.md). Not a real
+// assembler - just the handful of encodings these tests need, each with the
+// bit-layout spelled out so it can be checked against the ARM ARM directly
+// rather than trusted blindly.
+
+void Emit16(std::vector<uint8_t>& out, uint16_t hw) {
+    out.push_back((uint8_t)(hw & 0xFF));
+    out.push_back((uint8_t)(hw >> 8));
+}
+
+// PUSH {r4-r7, lr} - Thumb-16 "B5F0": 1011 010 L rrrrrrrr, L=1 (include LR),
+// register_list bits0-7 = r0..r7 presence (r4,r5,r6,r7 set = 0xF0).
+void EmitPushR4toR7Lr(std::vector<uint8_t>& out) {
+    Emit16(out, 0xB5F0);
+}
+
+// POP {r4-r7, pc} - Thumb-16 "BDF0": 1011 110 P rrrrrrrr, P=1 (include PC).
+void EmitPopR4toR7Pc(std::vector<uint8_t>& out) {
+    Emit16(out, 0xBDF0);
+}
+
+// MOVS Rd, #imm8 (Thumb-16, low registers r0-r7 only): 00100 ddd iiiiiiii.
+void EmitMovsImm8(std::vector<uint8_t>& out, uint8_t rd, uint8_t imm8) {
+    uint16_t hw = (uint16_t)(0x2000 | ((rd & 0x7) << 8) | imm8);
+    Emit16(out, hw);
+}
+
+// STR Rt, [Rn, #imm5*4] (Thumb-16, word, low registers): 01100 iiiii nnn ttt.
+void EmitStrImm5(std::vector<uint8_t>& out, uint8_t rt, uint8_t rn, uint8_t imm5) {
+    uint16_t hw = (uint16_t)(0x6000 | ((imm5 & 0x1F) << 6) | ((rn & 0x7) << 3) | (rt & 0x7));
+    Emit16(out, hw);
+}
+
+// BLX Rm (Thumb-16): 010001111 mmmm 000.
+void EmitBlxReg(std::vector<uint8_t>& out, uint8_t rm) {
+    uint16_t hw = (uint16_t)(0x4780 | ((rm & 0xF) << 3));
+    Emit16(out, hw);
+}
+
+// MOVW/MOVT Rd, #imm16 (Thumb-2, 32-bit, T3 encoding). First halfword:
+// 11110 i 10 op00 imm4 (op=0 MOVW/1 MOVT via bit5 of the "10 op00" group -
+// concretely opcode field bits[9:4] = 100100 for MOVW, 101100 for MOVT).
+// Second halfword: 0 imm3 Rd(4) imm8.
+void EmitMovWT(std::vector<uint8_t>& out, bool isMovt, uint8_t rd, uint16_t imm16) {
+    uint16_t imm4 = (imm16 >> 12) & 0xF;
+    uint16_t i    = (imm16 >> 11) & 0x1;
+    uint16_t imm3 = (imm16 >> 8) & 0x7;
+    uint16_t imm8 = imm16 & 0xFF;
+    uint16_t hw1 = (uint16_t)(0xF000 | (i << 10) | (isMovt ? 0x02C0 : 0x0240) | imm4);
+    uint16_t hw2 = (uint16_t)((imm3 << 12) | ((rd & 0xF) << 8) | imm8);
+    Emit16(out, hw1);
+    Emit16(out, hw2);
+}
+
+// Loads a full 32-bit guest address into Rd via MOVW (low 16) + MOVT (high 16).
+void EmitLoadAddr32(std::vector<uint8_t>& out, uint8_t rd, uint32_t addr) {
+    EmitMovWT(out, /*isMovt=*/false, rd, (uint16_t)(addr & 0xFFFF));
+    EmitMovWT(out, /*isMovt=*/true, rd, (uint16_t)(addr >> 16));
+}
+
+// BX LR (Thumb-16): 010001110 mmmm 000, Rm=LR(1110).
+void EmitBxLr(std::vector<uint8_t>& out) {
+    Emit16(out, 0x4770);
+}
+
+// LDR Rt, [SP, #imm8*4] (Thumb-16, SP-relative load): 10011 ttt iiiiiiii.
+// Reads a stack slot directly without needing SP loaded into a general
+// register first - exactly what a function reading its own stack-passed
+// arguments (AAPCS32, args beyond the first 4) does.
+void EmitLdrSpImm8(std::vector<uint8_t>& out, uint8_t rt, uint8_t imm8) {
+    uint16_t hw = (uint16_t)(0x9800 | ((rt & 0x7) << 8) | imm8);
+    Emit16(out, hw);
+}
+
+// No-op stub callback - deliberately does NOTHING to guest registers beyond
+// what AllocCodeStub's own dispatch (MiscStubDispatch/whatever fires this)
+// does on its own, matching a REAL import shim as closely as possible
+// (RegisterImportShim's own real-shim path reads r0-r3/sp and writes r0 -
+// see import_stub_dispatch_cb in guest_engine.cpp - this callback is
+// exactly that same shape, just with trivial body).
+uint32_t g_calleeSavedTestNoopHits = 0;
+void CalleeSavedTestNoopCb(uc_engine*, uint64_t, uint32_t, void*) {
+    g_calleeSavedTestNoopHits++;
+}
+
+// Reentrant-test stub callback - userData carries the "inner" guest
+// function's address (Thumb-tagged). Calling GuestEngine::CallGuestFunction
+// from WITHIN a UC_HOOK_CODE callback exercises the exact same "shim needs
+// to call back into guest code" shape as a real JNI upcall, deliberately
+// nested one level inside the outer test call this file already builds.
+uint32_t g_reentrantTestStubHits = 0;
+void ReentrantTestStubCb(uc_engine*, uint64_t, uint32_t, void* userData) {
+    g_reentrantTestStubHits++;
+    GuestAddr innerAddr = (GuestAddr)(uintptr_t)userData;
+    GuestEngine::Instance().CallGuestFunction(innerAddr);
+}
+
+// Real bytes of sub_4EDAD4 (0x4edad4, 56 bytes), copied verbatim from
+// native_lib/libapp.so via IDA - the exact FNV-1a hash-update loop this
+// session root-caused and shimmed (guest_engine.cpp's FnvHashAccelHookCb).
+// ARM-mode (not Thumb) machine code:
+//   push {r11, lr}
+//   mov r11, sp
+//   cmp r2, #1
+//   blt <exit>
+//   loop:
+//     ldrb r3, [r1], #1     ; r4 = *bytes++  (actual reg numbers per IDA)
+//     ...multiply by 16777619, xor, store...
+//     subs r2, r2, #1
+//     bne loop
+//   exit:
+//   pop {r11, pc}
+const uint8_t kFnvCode[] = {
+    0x00, 0x48, 0x2d, 0xe9, 0x0d, 0xb0, 0xa0, 0xe1, 0x01, 0x00, 0x52, 0xe3, 0x00, 0x88, 0xbd, 0xb8,
+    0x00, 0x30, 0x90, 0xe5, 0x93, 0xc1, 0x00, 0xe3, 0x00, 0xc1, 0x40, 0xe3, 0x93, 0x0c, 0x0e, 0xe0,
+    0x01, 0x30, 0xd1, 0xe4, 0x01, 0x20, 0x52, 0xe2, 0x03, 0x30, 0x2e, 0xe0, 0x00, 0x30, 0x80, 0xe5,
+    0xf9, 0xff, 0xff, 0x1a, 0x00, 0x88, 0xbd, 0xe8,
+};
+
+constexpr uint64_t kCodeAddr = 0x1000;
+constexpr uint64_t kCodeSize = 0x1000;
+constexpr uint64_t kResultAddr = 0x2000;
+constexpr uint64_t kResultSize = 0x1000;
+constexpr uint64_t kStackAddr = 0x9000;
+constexpr uint64_t kStackSize = 0x1000;
+constexpr uint64_t kDataAddr = 0x10000000;
+constexpr uint64_t kDataSize = 16u * 1024 * 1024; // 16 MiB - representative of a real .sb bundle section
+constexpr uint64_t kSentinelReturn = 0xfffffff0u;  // never mapped - uc_emu_start's `until` stops here cleanly
+
+} // namespace
+
+void RunTcgBenchmark() {
+    uc_engine* uc = nullptr;
+    uc_err err = uc_open(UC_ARCH_ARM, UC_MODE_ARM, &uc);
+    if (err != UC_ERR_OK) {
+        __android_log_print(ANDROID_LOG_INFO, "TCG_BENCH", "uc_open failed: %d", (int)err);
+        return;
+    }
+
+    uc_mem_map(uc, kCodeAddr, kCodeSize, UC_PROT_ALL);
+    uc_mem_map(uc, kResultAddr, kResultSize, UC_PROT_ALL);
+    uc_mem_map(uc, kStackAddr, kStackSize, UC_PROT_ALL);
+    uc_mem_map(uc, kDataAddr, kDataSize, UC_PROT_ALL);
+
+    uc_mem_write(uc, kCodeAddr, kFnvCode, sizeof(kFnvCode));
+
+    std::vector<uint8_t> dummy(kDataSize, 0x5a);
+    uc_mem_write(uc, kDataAddr, dummy.data(), dummy.size());
+
+    uint32_t hashState = 2166136261u; // FNV-1a offset basis
+    uc_mem_write(uc, kResultAddr, &hashState, sizeof(hashState));
+
+    uint32_t r0 = (uint32_t)kResultAddr;
+    uint32_t r1 = (uint32_t)kDataAddr;
+    uint32_t r2 = (uint32_t)kDataSize;
+    uint32_t sp = (uint32_t)(kStackAddr + kStackSize - 0x100);
+    uint32_t lr = kSentinelReturn;
+    uc_reg_write(uc, UC_ARM_REG_R0, &r0);
+    uc_reg_write(uc, UC_ARM_REG_R1, &r1);
+    uc_reg_write(uc, UC_ARM_REG_R2, &r2);
+    uc_reg_write(uc, UC_ARM_REG_SP, &sp);
+    uc_reg_write(uc, UC_ARM_REG_LR, &lr);
+
+    auto t0 = std::chrono::steady_clock::now();
+    err = uc_emu_start(uc, kCodeAddr, kSentinelReturn, 0, 0);
+    auto t1 = std::chrono::steady_clock::now();
+
+    double seconds = std::chrono::duration<double>(t1 - t0).count();
+    double bytesPerSec = seconds > 0 ? (double)kDataSize / seconds : 0.0;
+    double itersPerSec = seconds > 0 ? (double)kDataSize / seconds : 0.0;
+
+    __android_log_print(ANDROID_LOG_INFO, "TCG_BENCH",
+        "uc_emu_start rc=%d, %llu bytes in %.4fs = %.0f bytes/sec (%.0f iterations/sec) - "
+        "bare Unicorn/TCG, zero shims/hooks/game code involved",
+        (int)err, (unsigned long long)kDataSize, seconds, bytesPerSec, itersPerSec);
+
+    uc_close(uc);
+}
+
+void RunTcgBenchmarkInRealContext(GuestEngine& engine) {
+    // Keep this modest relative to the real 64 MiB guest heap (kHeapSize,
+    // guest_engine.cpp) - this runs after the real image and JNI_OnLoad
+    // have already claimed some of it, and this is a measurement, not a
+    // stress test.
+    constexpr uint32_t kBufSize = 4u * 1024 * 1024; // 4 MiB
+
+    GuestAddr codeAddr = engine.AllocPermanent((uint32_t)sizeof(kFnvCode));
+    GuestAddr resultAddr = engine.AllocPermanent(4);
+    GuestAddr dataAddr = engine.heap().Alloc(kBufSize);
+    if (!codeAddr || !resultAddr || !dataAddr) {
+        __android_log_print(ANDROID_LOG_INFO, "TCG_BENCH",
+            "RunTcgBenchmarkInRealContext: allocation failed (code=0x%x result=0x%x data=0x%x)",
+            codeAddr, resultAddr, dataAddr);
+        return;
+    }
+
+    memcpy(engine.G2H(codeAddr), kFnvCode, sizeof(kFnvCode));
+    memset(engine.G2H(dataAddr), 0x5a, kBufSize);
+    uint32_t hashState = 2166136261u;
+    memcpy(engine.G2H(resultAddr), &hashState, sizeof(hashState));
+
+    auto t0 = std::chrono::steady_clock::now();
+    engine.CallGuestFunction(codeAddr, resultAddr, dataAddr, kBufSize, 0);
+    auto t1 = std::chrono::steady_clock::now();
+
+    double seconds = std::chrono::duration<double>(t1 - t0).count();
+    double bytesPerSec = seconds > 0 ? (double)kBufSize / seconds : 0.0;
+
+    __android_log_print(ANDROID_LOG_INFO, "TCG_BENCH",
+        "RunTcgBenchmarkInRealContext: %u bytes in %.4fs = %.0f bytes/sec - "
+        "REAL loaded engine (whole game image + all hooks active), identical instruction bytes, "
+        "invoked via the same CallGuestFunction() every real guest call uses",
+        kBufSize, seconds, bytesPerSec);
+}
+
+void RunCalleeSavedRegisterTest(GuestEngine& engine) {
+    // Register a stub via the EXACT mechanism every real GLESv2/libc import
+    // shim uses (AllocCodeStub -> real Thumb `BX LR` + MiscStubDispatch's
+    // O(1) table lookup - see guest_engine.cpp). The callback itself does
+    // nothing (see CalleeSavedTestNoopCb above) - the point is to isolate
+    // whether the DISPATCH MECHANISM itself preserves callee-saved
+    // registers (AAPCS32: r4-r11 must survive a function call unchanged),
+    // not any particular shim's own logic.
+    GuestAddr stubAddr = engine.AllocCodeStub(CalleeSavedTestNoopCb, nullptr);
+    if (!stubAddr) {
+        __android_log_print(ANDROID_LOG_INFO, "REG_TEST",
+            "RunCalleeSavedRegisterTest: AllocCodeStub failed");
+        return;
+    }
+    GuestAddr resultsAddr = engine.AllocPermanent(16); // r4,r5,r6,r7 post-call snapshot
+    GuestAddr codeAddr = engine.AllocPermanent(64);    // generous - real size is ~24 bytes
+    if (!resultsAddr || !codeAddr) {
+        __android_log_print(ANDROID_LOG_INFO, "REG_TEST",
+            "RunCalleeSavedRegisterTest: allocation failed (results=0x%x code=0x%x)",
+            resultsAddr, codeAddr);
+        return;
+    }
+
+    // stubAddr already carries the Thumb tag (bit0=1) from AllocCodeStub's
+    // own return convention - BLX needs that same tag to switch/stay in
+    // Thumb mode, so use it as-is (not the raw, untagged address).
+    std::vector<uint8_t> code;
+    EmitPushR4toR7Lr(code);                       // preserve OUR OWN caller's r4-r7/lr
+    EmitMovsImm8(code, /*rd=*/4, 0x44);            // r4 = sentinel 0x44
+    EmitMovsImm8(code, /*rd=*/5, 0x55);            // r5 = sentinel 0x55
+    EmitMovsImm8(code, /*rd=*/6, 0x66);            // r6 = sentinel 0x66 (the exact register the real bug showed corrupted)
+    EmitMovsImm8(code, /*rd=*/7, 0x77);            // r7 = sentinel 0x77
+    EmitLoadAddr32(code, /*rd=*/0, stubAddr);      // r0 = stub address (Thumb-tagged)
+    EmitBlxReg(code, /*rm=*/0);                    // call it - real import-stub call path
+    EmitLoadAddr32(code, /*rd=*/1, resultsAddr);   // r1 = results buffer
+    EmitStrImm5(code, /*rt=*/4, /*rn=*/1, /*imm5=*/0); // results[0] = r4 (post-call)
+    EmitStrImm5(code, /*rt=*/5, /*rn=*/1, /*imm5=*/1); // results[1] = r5
+    EmitStrImm5(code, /*rt=*/6, /*rn=*/1, /*imm5=*/2); // results[2] = r6
+    EmitStrImm5(code, /*rt=*/7, /*rn=*/1, /*imm5=*/3); // results[3] = r7
+    EmitPopR4toR7Pc(code);                         // restore OUR caller's r4-r7, return via pc
+
+    memcpy(engine.G2H(codeAddr), code.data(), code.size());
+
+    uint32_t before = g_calleeSavedTestNoopHits;
+    engine.CallGuestFunction(codeAddr | 1u); // Thumb-tagged entry, no args needed
+    bool stubWasHit = g_calleeSavedTestNoopHits > before;
+
+    uint32_t results[4] = {0, 0, 0, 0};
+    memcpy(results, engine.G2H(resultsAddr), sizeof(results));
+    const uint32_t expected[4] = {0x44, 0x55, 0x66, 0x77};
+    const char* names[4] = {"r4", "r5", "r6", "r7"};
+    bool anyClobbered = false;
+    char summary[256] = {0};
+    int off = 0;
+    for (int i = 0; i < 4; i++) {
+        bool ok = results[i] == expected[i];
+        if (!ok) anyClobbered = true;
+        off += snprintf(summary + off, sizeof(summary) - off, "%s=0x%x(%s) ",
+                         names[i], results[i], ok ? "OK" : "CLOBBERED");
+    }
+    __android_log_print(ANDROID_LOG_INFO, "REG_TEST",
+        "RunCalleeSavedRegisterTest: stub_hit=%s result=%s | %s",
+        stubWasHit ? "yes" : "NO(!)",
+        anyClobbered ? "FAIL - callee-saved register(s) clobbered by the import-stub dispatch path"
+                      : "PASS - all callee-saved registers survived the stub call intact",
+        summary);
+}
+
+void RunReentrantCallRegisterTest(GuestEngine& engine) {
+    // Inner guest function: MOVS r0, #0x99 ; BX LR - trivial, just needs to
+    // be a real, callable guest function for CallGuestFunction to run.
+    std::vector<uint8_t> innerCode;
+    EmitMovsImm8(innerCode, /*rd=*/0, 0x99);
+    EmitBxLr(innerCode);
+    GuestAddr innerAddr = engine.AllocPermanent(16);
+    if (!innerAddr) {
+        __android_log_print(ANDROID_LOG_INFO, "REG_TEST", "RunReentrantCallRegisterTest: inner alloc failed");
+        return;
+    }
+    memcpy(engine.G2H(innerAddr), innerCode.data(), innerCode.size());
+
+    // Stub whose C++ callback reenters the guest via CallGuestFunction -
+    // userData carries the Thumb-tagged inner function address.
+    GuestAddr stubAddr = engine.AllocCodeStub(ReentrantTestStubCb, (void*)(uintptr_t)(innerAddr | 1u));
+    GuestAddr resultsAddr = engine.AllocPermanent(16);
+    GuestAddr codeAddr = engine.AllocPermanent(64);
+    if (!stubAddr || !resultsAddr || !codeAddr) {
+        __android_log_print(ANDROID_LOG_INFO, "REG_TEST",
+            "RunReentrantCallRegisterTest: allocation failed (stub=0x%x results=0x%x code=0x%x)",
+            stubAddr, resultsAddr, codeAddr);
+        return;
+    }
+
+    // Same outer shape as RunCalleeSavedRegisterTest - sentinels in r4-r7,
+    // call the stub (which now reenters CallGuestFunction internally
+    // instead of just returning), snapshot r4-r7 afterward.
+    std::vector<uint8_t> code;
+    EmitPushR4toR7Lr(code);
+    EmitMovsImm8(code, 4, 0x14);
+    EmitMovsImm8(code, 5, 0x15);
+    EmitMovsImm8(code, 6, 0x16);
+    EmitMovsImm8(code, 7, 0x17);
+    EmitLoadAddr32(code, 0, stubAddr);
+    EmitBlxReg(code, 0);
+    EmitLoadAddr32(code, 1, resultsAddr);
+    EmitStrImm5(code, 4, 1, 0);
+    EmitStrImm5(code, 5, 1, 1);
+    EmitStrImm5(code, 6, 1, 2);
+    EmitStrImm5(code, 7, 1, 3);
+    EmitPopR4toR7Pc(code);
+
+    memcpy(engine.G2H(codeAddr), code.data(), code.size());
+
+    uint32_t before = g_reentrantTestStubHits;
+    engine.CallGuestFunction(codeAddr | 1u);
+    bool stubWasHit = g_reentrantTestStubHits > before;
+
+    uint32_t results[4] = {0, 0, 0, 0};
+    memcpy(results, engine.G2H(resultsAddr), sizeof(results));
+    const uint32_t expected[4] = {0x14, 0x15, 0x16, 0x17};
+    const char* names[4] = {"r4", "r5", "r6", "r7"};
+    bool anyClobbered = false;
+    char summary[256] = {0};
+    int off = 0;
+    for (int i = 0; i < 4; i++) {
+        bool ok = results[i] == expected[i];
+        if (!ok) anyClobbered = true;
+        off += snprintf(summary + off, sizeof(summary) - off, "%s=0x%x(%s) ",
+                         names[i], results[i], ok ? "OK" : "CLOBBERED");
+    }
+    __android_log_print(ANDROID_LOG_INFO, "REG_TEST",
+        "RunReentrantCallRegisterTest: stub_hit=%s result=%s | %s",
+        stubWasHit ? "yes" : "NO(!)",
+        anyClobbered ? "FAIL - outer call's callee-saved register(s) clobbered by a nested reentrant CallGuestFunction"
+                      : "PASS - outer call's callee-saved registers survived a nested reentrant call intact",
+        summary);
+}
+
+void RunStackArgMarshalingTest(GuestEngine& engine) {
+    // Leaf function - deliberately never pushes/pops or calls anything else,
+    // so there's no need to preserve r4-r7 for a caller beyond this test's
+    // own use of them as scratch. Reads r0-r3 (register-passed args 0-3)
+    // FIRST (before overwriting them), storing each straight to the results
+    // buffer via r4 (loaded once, untouched by anything else here), THEN
+    // reuses r0-r3 as scratch to read the stack-passed args 4-7 directly
+    // via SP-relative loads (exactly where CallGuestFunction's own
+    // marshaling is documented to place them: [sp+0]=args[4], [sp+4]=
+    // args[5], [sp+8]=args[6], [sp+12]=args[7]).
+    GuestAddr resultsAddr = engine.AllocPermanent(32); // 8 x uint32_t
+    GuestAddr codeAddr = engine.AllocPermanent(96);
+    if (!resultsAddr || !codeAddr) {
+        __android_log_print(ANDROID_LOG_INFO, "REG_TEST",
+            "RunStackArgMarshalingTest: allocation failed (results=0x%x code=0x%x)",
+            resultsAddr, codeAddr);
+        return;
+    }
+
+    std::vector<uint8_t> code;
+    EmitLoadAddr32(code, /*rd=*/4, resultsAddr);
+    EmitStrImm5(code, /*rt=*/0, /*rn=*/4, /*imm5=*/0); // results[0] = arg0 (r0)
+    EmitStrImm5(code, /*rt=*/1, /*rn=*/4, /*imm5=*/1); // results[1] = arg1 (r1)
+    EmitStrImm5(code, /*rt=*/2, /*rn=*/4, /*imm5=*/2); // results[2] = arg2 (r2)
+    EmitStrImm5(code, /*rt=*/3, /*rn=*/4, /*imm5=*/3); // results[3] = arg3 (r3)
+    EmitLdrSpImm8(code, /*rt=*/0, /*imm8=*/0); // r0 = [sp+0] = arg4
+    EmitStrImm5(code, /*rt=*/0, /*rn=*/4, /*imm5=*/4);
+    EmitLdrSpImm8(code, /*rt=*/0, /*imm8=*/1); // r0 = [sp+4] = arg5
+    EmitStrImm5(code, /*rt=*/0, /*rn=*/4, /*imm5=*/5);
+    EmitLdrSpImm8(code, /*rt=*/0, /*imm8=*/2); // r0 = [sp+8] = arg6
+    EmitStrImm5(code, /*rt=*/0, /*rn=*/4, /*imm5=*/6);
+    EmitLdrSpImm8(code, /*rt=*/0, /*imm8=*/3); // r0 = [sp+12] = arg7
+    EmitStrImm5(code, /*rt=*/0, /*rn=*/4, /*imm5=*/7);
+    EmitBxLr(code);
+
+    memcpy(engine.G2H(codeAddr), code.data(), code.size());
+
+    const uint32_t sentinels[8] = {0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17};
+    engine.CallGuestFunction(codeAddr | 1u, sentinels, 8);
+
+    uint32_t results[8] = {0};
+    memcpy(results, engine.G2H(resultsAddr), sizeof(results));
+    bool anyWrong = false;
+    char summary[384] = {0};
+    int off = 0;
+    for (int i = 0; i < 8; i++) {
+        bool ok = results[i] == sentinels[i];
+        if (!ok) anyWrong = true;
+        off += snprintf(summary + off, sizeof(summary) - off, "arg%d=0x%x(%s) ",
+                         i, results[i], ok ? "OK" : "WRONG");
+    }
+    __android_log_print(ANDROID_LOG_INFO, "REG_TEST",
+        "RunStackArgMarshalingTest: result=%s | %s",
+        anyWrong ? "FAIL - stack-passed argument(s) (argCount>4) marshaled incorrectly"
+                 : "PASS - all 4 register args and 4 stack-marshaled args (argCount=8) arrived correctly",
+        summary);
+}
+
+void RunSequentialCallStateLeakTest(GuestEngine& engine) {
+    // Reuses CalleeSavedTestNoopCb (the same trivial no-op stub
+    // RunCalleeSavedRegisterTest already validated preserves r4-r7 within
+    // ONE call) - this test's question is different: does calling the
+    // SAME stub, through the SAME dispatch table entry, on the SAME
+    // thread, MULTIPLE TIMES IN A ROW (not nested/reentrant - each call
+    // fully completes before the next starts) ever let one call's state
+    // leak into another's, e.g. via a caching bug in CallGuestFunction's
+    // save/restore bookkeeping or AllocCodeStub/MiscStubDispatch's table
+    // lookup that only manifests on a second or third call.
+    GuestAddr stubAddr = engine.AllocCodeStub(CalleeSavedTestNoopCb, nullptr);
+    GuestAddr resultsAddr = engine.AllocPermanent(16);
+    GuestAddr codeAddr = engine.AllocPermanent(64);
+    if (!stubAddr || !resultsAddr || !codeAddr) {
+        __android_log_print(ANDROID_LOG_INFO, "REG_TEST",
+            "RunSequentialCallStateLeakTest: allocation failed (stub=0x%x results=0x%x code=0x%x)",
+            stubAddr, resultsAddr, codeAddr);
+        return;
+    }
+
+    // Same shape as RunCalleeSavedRegisterTest, but the sentinel values are
+    // baked into three SEPARATE code buffers (one per call) so each call's
+    // expected values are unambiguous and distinct from the others -
+    // avoids any chance of a false PASS from comparing against a leftover
+    // value that just happens to equal what THIS call wrote anyway.
+    struct Round { uint32_t sentinels[4]; GuestAddr codeAddr; };
+    Round rounds[3] = {
+        {{0x21, 0x22, 0x23, 0x24}, 0},
+        {{0x31, 0x32, 0x33, 0x34}, 0},
+        {{0x41, 0x42, 0x43, 0x44}, 0},
+    };
+
+    bool allocOk = true;
+    for (auto& round : rounds) {
+        round.codeAddr = engine.AllocPermanent(64);
+        if (!round.codeAddr) { allocOk = false; break; }
+        std::vector<uint8_t> code;
+        EmitPushR4toR7Lr(code);
+        EmitMovsImm8(code, 4, (uint8_t)round.sentinels[0]);
+        EmitMovsImm8(code, 5, (uint8_t)round.sentinels[1]);
+        EmitMovsImm8(code, 6, (uint8_t)round.sentinels[2]);
+        EmitMovsImm8(code, 7, (uint8_t)round.sentinels[3]);
+        EmitLoadAddr32(code, 0, stubAddr);
+        EmitBlxReg(code, 0);
+        EmitLoadAddr32(code, 1, resultsAddr);
+        EmitStrImm5(code, 4, 1, 0);
+        EmitStrImm5(code, 5, 1, 1);
+        EmitStrImm5(code, 6, 1, 2);
+        EmitStrImm5(code, 7, 1, 3);
+        EmitPopR4toR7Pc(code);
+        memcpy(engine.G2H(round.codeAddr), code.data(), code.size());
+    }
+    if (!allocOk) {
+        __android_log_print(ANDROID_LOG_INFO, "REG_TEST",
+            "RunSequentialCallStateLeakTest: per-round code allocation failed");
+        return;
+    }
+
+    bool anyFailed = false;
+    char summary[512] = {0};
+    int off = 0;
+    for (int r = 0; r < 3; r++) {
+        // Poison the results buffer with a recognizable non-sentinel value
+        // between rounds - a leftover-value false PASS is impossible here,
+        // since 0xDEADBEEF never matches any round's real sentinels.
+        uint32_t poison[4] = {0xDEADBEEFu, 0xDEADBEEFu, 0xDEADBEEFu, 0xDEADBEEFu};
+        memcpy(engine.G2H(resultsAddr), poison, sizeof(poison));
+
+        engine.CallGuestFunction(rounds[r].codeAddr | 1u);
+
+        uint32_t results[4] = {0};
+        memcpy(results, engine.G2H(resultsAddr), sizeof(results));
+        bool roundOk = true;
+        for (int i = 0; i < 4; i++) {
+            if (results[i] != rounds[r].sentinels[i]) roundOk = false;
+        }
+        if (!roundOk) anyFailed = true;
+        off += snprintf(summary + off, sizeof(summary) - off,
+                         "round%d=%s[0x%x,0x%x,0x%x,0x%x] ", r, roundOk ? "OK" : "FAIL",
+                         results[0], results[1], results[2], results[3]);
+    }
+    __android_log_print(ANDROID_LOG_INFO, "REG_TEST",
+        "RunSequentialCallStateLeakTest: result=%s | %s",
+        anyFailed ? "FAIL - state leaked across sequential (non-reentrant) calls"
+                  : "PASS - three sequential calls to the same stub each saw only their own sentinels",
+        summary);
+}

mpcore/src/main/cpp/emu/tcg_bench.h

@@ -0,0 +1,88 @@
+#pragma once
+
+class GuestEngine;
+
+// One-shot, throwaway benchmark (2026-09-06, ARM64_TRANSLATION_LAYER.md -
+// "is Unicorn/QEMU-TCG itself the bottleneck, or just this project's own
+// overhead on top of it" question, raised directly by the user comparing
+// against libhoudini's own ARM32->x86_64 translation achieving good
+// real-world game performance). Runs the EXACT real machine code bytes of
+// sub_4EDAD4 (the FNV-1a hash loop already root-caused and shimmed this
+// session) on a brand-new, hook-free uc_engine with no relationship to
+// GuestEngine/the loaded game image at all - the purest possible measure
+// of "what can bare Unicorn/TCG achieve for this exact instruction
+// sequence," isolated from every other project-specific cost this session
+// already found and fixed (uc_emu_stop() round-trips, GuestHeap's O(n)
+// scan, per-block hook overhead). Call once, log the result, then remove.
+void RunTcgBenchmark();
+
+// Same measurement, same exact instruction bytes, but run INSIDE the real,
+// fully-loaded GuestEngine (whole ~9+ MB game image mapped, every other
+// hook this project registers still active, invoked via the same
+// CallGuestFunction() every other real guest call in this codebase uses) -
+// via a scratch copy of the code at a different address so it doesn't hit
+// FnvHashAccelHookCb's own address-pinned skip. Directly answers: is bare
+// Unicorn/TCG itself slower once the real binary is loaded (translation-
+// cache pressure being the leading candidate), or is the gap this
+// session's earlier real-world measurements found actually coming from
+// surrounding work (marshaling, allocations, other per-call bookkeeping)
+// rather than the instruction-emulation cost of the loop itself?
+void RunTcgBenchmarkInRealContext(GuestEngine& engine);
+
+// Synthetic unit test (2026-09-16, ARM64_TRANSLATION_LAYER.md - the
+// sub_43FDE0/dword_ADBFB8 investigation). Real game code shows a
+// callee-saved register (R6, holding a value that should survive
+// unchanged across several nested guest-to-guest BL calls including real
+// GLESv2 import calls like glUseProgram/glVertexAttribPointer) ending up
+// corrupted by the time it's read many instructions later. Rather than
+// keep tracing further through real, complex game code, this builds a
+// minimal synthetic guest function that: sets R4-R7 to known sentinel
+// values, calls a stub allocated via the EXACT SAME AllocCodeStub/
+// MiscStubDispatch/import_stub_dispatch_cb mechanism every real GLES
+// import shim uses (not a simplified stand-in), then checks whether R4-R7
+// still hold their sentinels. Directly tests whether the import-stub call
+// path preserves callee-saved registers (AAPCS32) - isolates the
+// mechanism in one controlled call instead of chasing it through real
+// game logic. Logs a bitmask of which registers (if any) got clobbered.
+void RunCalleeSavedRegisterTest(GuestEngine& engine);
+
+// Same idea, but for the REENTRANT case: a stub callback that itself
+// triggers a nested CallGuestFunction() from within its own C++ body
+// (matching what a JNI upcall or any "shim needs to call back into guest
+// code" path does - CallGuestFunction's own elaborate save/restore of
+// r0-r12/sp/lr/pc/cpsr + all 32 D-registers exists specifically for this
+// case, per its own comment in guest_engine.cpp). Verifies the OUTER,
+// suspended call's callee-saved registers survive a nested nested call
+// correctly - a much less-exercised path than a single flat stub call.
+void RunReentrantCallRegisterTest(GuestEngine& engine);
+
+// Synthetic unit test (2026-09-16, ARM64_TRANSLATION_LAYER.md - the
+// broader "покрой синтетикой весь свой код" directive, and specifically
+// the earlier-in-session "Копай CallGuestFunction и маршалинг
+// stack-аргументов" instruction that was never actually followed up with a
+// dedicated test). `CallGuestFunction(target, args, argCount)` marshals
+// argCount>4 by writing args[4..] onto the guest stack per AAPCS32
+// (args[4] at [sp+0], args[5] at [sp+4], ...) - real call sites depend on
+// this (JNI entry points with >4 params, arbitrary-arity Call*Method) but
+// it had no isolated correctness test of its own. Builds a minimal LEAF
+// guest function that reads r0-r3 (register-passed args) plus [sp+0],
+// [sp+4], [sp+8], [sp+12] (stack-passed args) directly, writes all 8 back
+// to a results buffer, and calls it with 8 known sentinel values via the
+// array-taking CallGuestFunction overload. Directly answers whether the
+// stack portion of the marshaling is correct (right values, right
+// alignment/offsets) rather than just the register portion every other
+// existing test already covers.
+void RunStackArgMarshalingTest(GuestEngine& engine);
+
+// Synthetic unit test (2026-09-16, ARM64_TRANSLATION_LAYER.md - same
+// broader coverage directive). Every existing register-preservation test
+// checks ONE call in isolation. This checks whether STATE LEAKS ACROSS
+// SEQUENTIAL (not nested/reentrant) calls on the same thread - e.g. a
+// caching bug in CallGuestFunction's own save/restore bookkeeping, or in
+// AllocCodeStub/MiscStubDispatch's table lookup, that only manifests on
+// the second or third call and not the first. Calls the SAME
+// AllocCodeStub-dispatched stub three times in a row, each time with
+// DIFFERENT sentinel values in r4-r7, checking after EACH call that only
+// THAT call's own sentinels come back (not a stale value from the
+// previous call).
+void RunSequentialCallStateLeakTest(GuestEngine& engine);

mpcore/src/main/cpp/emu/tests/guest_heap_test.cpp

@@ -0,0 +1,168 @@
+// Desktop-only test harness for GuestHeap (see /ARM64_TRANSLATION_LAYER.md
+// and guest_heap.h's own class comment) - no Unicorn, no Android, no APK.
+// Compiles and links ONLY guest_heap.cpp directly against a host-side stub
+// of util.h's Log() below (guest_heap.cpp is otherwise fully portable - see
+// guest_types.h). Run via mpcore/scripts/run_heap_tests.sh.
+//
+// Exercises exactly the failure mode a real on-device crash was traced to
+// this session: GuestHeap::Free() with a wrong/stale address silently
+// corrupting an unrelated live allocation (which, in the real crash, was
+// the permanently-cached guest JNIEnv). Confirms the canary added in
+// response catches it instead of letting it through.
+
+#include "../guest_heap.h"
+#include <cstdarg>
+#include <cstdio>
+#include <cstring>
+#include <vector>
+
+// util.h declares this; guest_heap.cpp calls it on rejected frees/
+// exhaustion. Desktop stand-in - prints to stdout instead of
+// __android_log_write (an NDK-only API, not available on the host).
+void Log(const char* fmt, ...) {
+    va_list args;
+    va_start(args, fmt);
+    vprintf(fmt, args);
+    va_end(args);
+    printf("\n");
+}
+
+namespace {
+
+int g_checks = 0;
+int g_failures = 0;
+
+void Check(bool cond, const char* what) {
+    g_checks++;
+    if (!cond) {
+        g_failures++;
+        printf("  FAIL: %s\n", what);
+    } else {
+        printf("  ok:   %s\n", what);
+    }
+}
+
+} // namespace
+
+int main() {
+    constexpr uint32_t kArenaSize = 64 * 1024;
+    constexpr GuestAddr kArenaStart = 0x1000; // nonzero, matches real usage (heap never starts at guest 0)
+    // Backing buffer is addressed the same way GuestEngine::G2H does
+    // (hostBase + guestAddr) - kArenaStart headroom below the arena itself
+    // so that convention holds without a separate translation helper here.
+    std::vector<uint8_t> backing(kArenaStart + kArenaSize, 0);
+
+    printf("test: basic alloc/free round trip\n");
+    {
+        GuestHeap heap;
+        heap.Init(backing.data(), kArenaStart, kArenaSize);
+        GuestAddr a = heap.Alloc(64);
+        Check(a != 0, "Alloc(64) succeeds");
+        heap.Free(a);
+        GuestAddr b = heap.Alloc(64);
+        Check(b == a, "Alloc after Free reuses the freed block (first-fit)");
+    }
+
+    printf("test: free(0) is a silent no-op, matching free(NULL)\n");
+    {
+        GuestHeap heap;
+        heap.Init(backing.data(), kArenaStart, kArenaSize);
+        heap.Free(0); // must not crash, must not touch anything
+        GuestAddr a = heap.Alloc(16);
+        Check(a != 0, "heap still works normally after Free(0)");
+    }
+
+    printf("test: double-free is rejected, not silently accepted\n");
+    {
+        GuestHeap heap;
+        heap.Init(backing.data(), kArenaStart, kArenaSize);
+        GuestAddr a = heap.Alloc(32);
+        heap.Free(a);
+        heap.Free(a); // second free of the same address - must be rejected, not corrupt bookkeeping
+        GuestAddr b = heap.Alloc(32);
+        Check(b == a, "block is still consistently reusable after an attempted double-free");
+    }
+
+    printf("test: a wrong/stale address passed to Free() does not corrupt a live neighbor\n");
+    {
+        GuestHeap heap;
+        heap.Init(backing.data(), kArenaStart, kArenaSize);
+        GuestAddr victim = heap.Alloc(16);
+        Check(victim != 0, "victim allocation succeeds");
+        memset(backing.data() + victim, 0xAB, 16); // sentinel payload
+
+        // NOT a real block's payload start - exactly the shape of bug this
+        // session traced a real crash to (a miscalculated/stale guest
+        // address handed to Free()).
+        GuestAddr wrongAddr = victim + 5;
+        heap.Free(wrongAddr); // must be rejected
+
+        bool intact = true;
+        for (int i = 0; i < 16; i++) {
+            if (backing.data()[victim + i] != 0xAB) intact = false;
+        }
+        Check(intact, "victim block's payload is untouched after a rejected wrong-address free");
+
+        // The victim should still be considered in-use - first-fit must
+        // skip it (not reuse it) for a fresh allocation.
+        GuestAddr other = heap.Alloc(16);
+        Check(other != victim, "victim block was NOT freed by the rejected wrong-address free");
+    }
+
+    printf("test: oversized (>64KiB) alloc/free round trip reuses the freed block\n");
+    {
+        // Separate, larger arena - the default 64KiB test arena above can't
+        // fit even one >64KiB allocation.
+        constexpr uint32_t kBigArenaSize = 4 * 1024 * 1024; // 4MiB
+        std::vector<uint8_t> bigBacking(kArenaStart + kBigArenaSize, 0);
+        GuestHeap heap;
+        heap.Init(bigBacking.data(), kArenaStart, kBigArenaSize);
+        GuestAddr a = heap.Alloc(175760); // real size from the sub_4BA588 crash log
+        Check(a != 0, "Alloc(175760) succeeds");
+        heap.Free(a);
+        GuestAddr b = heap.Alloc(175760);
+        Check(b == a, "oversized Alloc after Free reuses the freed block, same as small sizes");
+    }
+
+    printf("test: repeated oversized alloc/free does NOT grow the arena unboundedly "
+           "(regression test for the sub_4BA588/loadNodeUncached heap-exhaustion crash, "
+           "ARM64_TRANSLATION_LAYER.md 2026-09-18)\n");
+    {
+        // Small enough that the OLD never-reclaim behavior would exhaust
+        // this arena in well under 100 iterations (100 * (175760+12) ~=
+        // 17.6MB > this 1MB arena), but large enough that a handful of
+        // real, simultaneously-live oversized objects still fit alongside
+        // the reused ones - a tight, realistic regression bound instead of
+        // an arbitrarily generous one.
+        constexpr uint32_t kBigArenaSize = 1 * 1024 * 1024; // 1MiB
+        std::vector<uint8_t> bigBacking(kArenaStart + kBigArenaSize, 0);
+        GuestHeap heap;
+        heap.Init(bigBacking.data(), kArenaStart, kBigArenaSize);
+        bool allSucceeded = true;
+        for (int i = 0; i < 500; i++) {
+            GuestAddr a = heap.Alloc(175760);
+            if (a == 0) { allSucceeded = false; break; }
+            heap.Free(a);
+        }
+        Check(allSucceeded, "500 repeated alloc/free cycles of a real oversized size all "
+                             "succeed in a 1MiB arena (would have exhausted after ~5 cycles "
+                             "under the old never-reclaimed behavior)");
+    }
+
+    printf("test: exhaustion returns 0 (guest NULL), not garbage or a crash\n");
+    {
+        GuestHeap heap;
+        heap.Init(backing.data(), kArenaStart, kArenaSize);
+        int count = 0;
+        while (heap.Alloc(256) != 0) {
+            count++;
+            if (count > 100000) break; // safety valve
+        }
+        Check(count > 0, "at least one allocation succeeded before exhaustion");
+        GuestAddr overflow = heap.Alloc(256);
+        Check(overflow == 0, "allocation after exhaustion returns 0");
+    }
+
+    printf("\n%d checks, %d failures\n", g_checks, g_failures);
+    return g_failures == 0 ? 0 : 1;
+}

mpcore/src/main/cpp/emu/zlib_accel.cpp

@@ -0,0 +1,236 @@
+#include "zlib_accel.h"
+
+#include "guest_engine.h"
+#include "../util/util.h"
+
+#include <zlib.h>
+
+#include <atomic>
+#include <cstring>
+#include <map>
+#include <mutex>
+
+namespace zlib_accel {
+namespace {
+
+// z_stream on this 32-bit ABI (sizeof == 56, which inflateInit2_ itself
+// checks - see its decompile in ARM64_TRANSLATION_LAYER.md):
+constexpr uint32_t kOffNextIn = 0;
+constexpr uint32_t kOffAvailIn = 4;
+constexpr uint32_t kOffTotalIn = 8;
+constexpr uint32_t kOffNextOut = 12;
+constexpr uint32_t kOffAvailOut = 16;
+constexpr uint32_t kOffTotalOut = 20;
+constexpr uint32_t kOffMsg = 24;
+constexpr uint32_t kOffState = 28;
+constexpr uint32_t kOffAdler = 48;
+constexpr uint32_t kGuestZStreamSize = 56;
+
+std::mutex g_mutex;
+// guest z_stream address -> the host stream doing the real work.
+std::map<uint32_t, z_stream*> g_streams;
+
+std::atomic<uint64_t> g_calls{0};
+std::atomic<uint64_t> g_bytesOut{0};
+
+uint32_t ReadU32(uc_engine* uc, uint32_t addr) {
+    uint32_t v = 0;
+    uc_mem_read(uc, addr, &v, 4);
+    return v;
+}
+void WriteU32(uc_engine* uc, uint32_t addr, uint32_t v) { uc_mem_write(uc, addr, &v, 4); }
+
+// Returns from the intercepted guest function with `ret` in r0, without ever
+// executing its body - same mechanism as guest_engine.cpp's
+// FnvHashAccelHookCb (write PC=LR, stop the emulation so it resumes there).
+void ReturnToCaller(uc_engine* uc, uint32_t ret) {
+    uint32_t lr = 0;
+    uc_reg_read(uc, UC_ARM_REG_LR, &lr);
+    uc_reg_write(uc, UC_ARM_REG_R0, &ret);
+    uc_reg_write(uc, UC_ARM_REG_PC, &lr);
+    uc_emu_stop(uc);
+}
+
+z_stream* FindStream(uint32_t guestStrm) {
+    std::lock_guard<std::mutex> lock(g_mutex);
+    auto it = g_streams.find(guestStrm);
+    return it == g_streams.end() ? nullptr : it->second;
+}
+
+void HandleInit2(uc_engine* uc) {
+    uint32_t strm = 0, windowBits = 0, version = 0, streamSize = 0;
+    uc_reg_read(uc, UC_ARM_REG_R0, &strm);
+    uc_reg_read(uc, UC_ARM_REG_R1, &windowBits);
+    uc_reg_read(uc, UC_ARM_REG_R2, &version);
+    uc_reg_read(uc, UC_ARM_REG_R3, &streamSize);
+
+    // Mirror the real function's own argument validation exactly, so a
+    // caller that gets this wrong still sees the error code it expects
+    // rather than silently succeeding.
+    if (!version) { ReturnToCaller(uc, (uint32_t)Z_VERSION_ERROR); return; }
+    uint8_t versionFirst = 0;
+    uc_mem_read(uc, version, &versionFirst, 1);
+    if (streamSize != kGuestZStreamSize || versionFirst != '1') {
+        ReturnToCaller(uc, (uint32_t)Z_VERSION_ERROR);
+        return;
+    }
+    if (!strm) { ReturnToCaller(uc, (uint32_t)Z_STREAM_ERROR); return; }
+
+    auto* hs = new z_stream();
+    std::memset(hs, 0, sizeof(*hs));
+    // Host allocation on purpose: the guest's own zalloc/zfree hand out
+    // GuestHeap memory, and the window/state buffers are pure zlib internals
+    // the guest never looks at. Keeping them off the guest heap also keeps
+    // this acceleration from competing for the guest's own arena.
+    int ret = inflateInit2(hs, (int)windowBits);
+    if (ret != Z_OK) {
+        delete hs;
+        ReturnToCaller(uc, (uint32_t)ret);
+        return;
+    }
+
+    {
+        std::lock_guard<std::mutex> lock(g_mutex);
+        auto existing = g_streams.find(strm);
+        if (existing != g_streams.end()) {
+            // Re-init of an address we already own (the guest freed and
+            // reallocated a z_stream at the same address). Drop the old one
+            // rather than leaking it.
+            inflateEnd(existing->second);
+            delete existing->second;
+            existing->second = hs;
+        } else {
+            g_streams.emplace(strm, hs);
+        }
+    }
+
+    // Deliberately leave the guest's `state` NULL. Nothing in the guest
+    // dereferences it while we own the stream, and if some zlib entry point
+    // this layer does NOT intercept is ever called on this stream, zlib's
+    // own NULL-state check makes it return Z_STREAM_ERROR - a clean,
+    // debuggable failure instead of walking a fabricated pointer.
+    WriteU32(uc, strm + kOffState, 0);
+    WriteU32(uc, strm + kOffMsg, 0);
+    WriteU32(uc, strm + kOffTotalIn, 0);
+    WriteU32(uc, strm + kOffTotalOut, 0);
+    ReturnToCaller(uc, (uint32_t)Z_OK);
+}
+
+void HandleInflate(uc_engine* uc) {
+    uint32_t strm = 0, flush = 0;
+    uc_reg_read(uc, UC_ARM_REG_R0, &strm);
+    uc_reg_read(uc, UC_ARM_REG_R1, &flush);
+
+    z_stream* hs = strm ? FindStream(strm) : nullptr;
+    if (!hs) return; // not ours - let the original emulated code run
+
+    auto& eng = GuestEngine::Instance();
+    uint32_t nextIn = ReadU32(uc, strm + kOffNextIn);
+    uint32_t availIn = ReadU32(uc, strm + kOffAvailIn);
+    uint32_t nextOut = ReadU32(uc, strm + kOffNextOut);
+    uint32_t availOut = ReadU32(uc, strm + kOffAvailOut);
+
+    // The guest's buffers live in the same flat host region, so host zlib
+    // reads and writes them in place - no copying in or out.
+    hs->next_in = availIn ? (Bytef*)eng.G2H(nextIn) : nullptr;
+    hs->avail_in = availIn;
+    hs->next_out = availOut ? (Bytef*)eng.G2H(nextOut) : nullptr;
+    hs->avail_out = availOut;
+
+    int ret = inflate(hs, (int)flush);
+
+    uint32_t consumed = availIn - hs->avail_in;
+    uint32_t produced = availOut - hs->avail_out;
+    WriteU32(uc, strm + kOffNextIn, nextIn + consumed);
+    WriteU32(uc, strm + kOffAvailIn, hs->avail_in);
+    WriteU32(uc, strm + kOffNextOut, nextOut + produced);
+    WriteU32(uc, strm + kOffAvailOut, hs->avail_out);
+    WriteU32(uc, strm + kOffTotalIn, (uint32_t)hs->total_in);
+    WriteU32(uc, strm + kOffTotalOut, (uint32_t)hs->total_out);
+    WriteU32(uc, strm + kOffAdler, (uint32_t)hs->adler);
+    // msg points at a host string literal that the guest cannot read; leave
+    // it NULL rather than handing over an address outside the guest region.
+    WriteU32(uc, strm + kOffMsg, 0);
+
+    uint64_t n = g_calls.fetch_add(1, std::memory_order_relaxed) + 1;
+    uint64_t total = g_bytesOut.fetch_add(produced, std::memory_order_relaxed) + produced;
+    if (n % 2000 == 0) {
+        Log("zlib_accel: %llu native inflate calls, %.1fMB produced (host zlib, not emulated)",
+            (unsigned long long)n, total / (1024.0 * 1024.0));
+    }
+    ReturnToCaller(uc, (uint32_t)ret);
+}
+
+void HandleReset2(uc_engine* uc) {
+    uint32_t strm = 0, windowBits = 0;
+    uc_reg_read(uc, UC_ARM_REG_R0, &strm);
+    uc_reg_read(uc, UC_ARM_REG_R1, &windowBits);
+    z_stream* hs = strm ? FindStream(strm) : nullptr;
+    if (!hs) return; // not ours
+    int ret = inflateReset2(hs, (int)windowBits);
+    WriteU32(uc, strm + kOffTotalIn, 0);
+    WriteU32(uc, strm + kOffTotalOut, 0);
+    WriteU32(uc, strm + kOffMsg, 0);
+    ReturnToCaller(uc, (uint32_t)ret);
+}
+
+void HandleEnd(uc_engine* uc) {
+    uint32_t strm = 0;
+    uc_reg_read(uc, UC_ARM_REG_R0, &strm);
+    if (!strm) return; // not ours (and the real code returns Z_STREAM_ERROR)
+
+    z_stream* hs = nullptr;
+    {
+        std::lock_guard<std::mutex> lock(g_mutex);
+        auto it = g_streams.find(strm);
+        if (it == g_streams.end()) return; // not ours
+        hs = it->second;
+        g_streams.erase(it);
+    }
+    inflateEnd(hs);
+    delete hs;
+    WriteU32(uc, strm + kOffState, 0);
+    ReturnToCaller(uc, (uint32_t)Z_OK);
+}
+
+std::atomic<uint64_t> g_crcCalls{0};
+std::atomic<uint64_t> g_crcBytes{0};
+
+// crc32(uLong crc, const Bytef* buf, uInt len) - pure, so unlike inflate
+// there is no stream to own and nothing to fall back to: every call can be
+// served natively. Mirrors the real function's own `buf == NULL -> 0` case.
+void HandleCrc32(uc_engine* uc) {
+    uint32_t crc = 0, buf = 0, len = 0;
+    uc_reg_read(uc, UC_ARM_REG_R0, &crc);
+    uc_reg_read(uc, UC_ARM_REG_R1, &buf);
+    uc_reg_read(uc, UC_ARM_REG_R2, &len);
+
+    if (!buf) { ReturnToCaller(uc, 0); return; }
+
+    auto& eng = GuestEngine::Instance();
+    uint32_t result =
+        (uint32_t)::crc32((uLong)crc, (const Bytef*)eng.G2H(buf), (uInt)len);
+
+    uint64_t n = g_crcCalls.fetch_add(1, std::memory_order_relaxed) + 1;
+    uint64_t total = g_crcBytes.fetch_add(len, std::memory_order_relaxed) + len;
+    if (n % 20000 == 0) {
+        Log("zlib_accel: %llu native crc32 calls, %.1fMB checksummed (host, not emulated)",
+            (unsigned long long)n, total / (1024.0 * 1024.0));
+    }
+    ReturnToCaller(uc, result);
+}
+
+} // namespace
+
+void HookCb(uc_engine* uc, uint64_t address, uint32_t, void*) {
+    switch (address) {
+        case kInflateInit2Addr: HandleInit2(uc); break;
+        case kInflateAddr: HandleInflate(uc); break;
+        case kInflateReset2Addr: HandleReset2(uc); break;
+        case kInflateEndAddr: HandleEnd(uc); break;
+        case kCrc32Addr: HandleCrc32(uc); break;
+        default: break;
+    }
+}
+
+} // namespace zlib_accel

mpcore/src/main/cpp/emu/zlib_accel.h

@@ -0,0 +1,53 @@
+#pragma once
+
+#include <unicorn/unicorn.h>
+
+// Native acceleration for the zlib inflate family that is STATICALLY LINKED
+// into libapp.so (zlib 1.2.5 - confirmed by its embedded copyright string;
+// the binary imports no libz.so and has no inflate/crc32 dynamic symbols).
+// Because it is statically linked it runs as guest ARM32 code through
+// Unicorn, i.e. at the measured ~12.8M instructions/sec against a native
+// core's ~1G. Decompression costs roughly 10-30 instructions per output byte,
+// and a single load was measured producing 66.2MB from ONE stream - minutes
+// of pure emulation. See ARM64_TRANSLATION_LAYER.md (task #43).
+//
+// The interception follows the same mechanism as FnvHashAccelHookCb
+// (guest_engine.cpp): a UC_HOOK_CODE at the function's entry address, the
+// work done natively, then PC=LR and uc_emu_stop so the guest body never
+// runs. The difference, and the reason this needs its own file: FNV-1a was a
+// pure function, whereas inflate is STATEFUL - the state is created by
+// inflateInit2_ and threaded through many inflate() calls - so the whole
+// family has to be taken over together, with a real host z_stream kept per
+// guest stream.
+//
+// SAFETY: a stream is only taken over if this layer saw its own
+// inflateInit2_ go through. libapp.so has nine distinct callers of inflate
+// (libpng among them, with its own streams and its own use of functions this
+// layer does not intercept); any stream this layer does not recognise is left
+// entirely alone and runs the original emulated code, slowly but correctly.
+//
+// Guest addresses below are from this exact libapp.so build:
+//   inflateInit2_  0x667D64  (strm, windowBits, version, stream_size)
+//   inflateReset2  0x667C44  (strm, windowBits)
+//   inflate        0x667FFC  (strm, flush)
+//   inflateEnd     0x669B64  (strm)
+namespace zlib_accel {
+
+constexpr uint64_t kInflateInit2Addr = 0x667d64;
+constexpr uint64_t kInflateReset2Addr = 0x667c44;
+constexpr uint64_t kInflateAddr = 0x667ffc;
+constexpr uint64_t kInflateEndAddr = 0x669b64;
+// zlib's crc32(crc, buf, len) - identified by its ~crc on entry and exit, the
+// 8x256 slice-by-8 table at dword_A40B84, and the 32-byte unrolled loop.
+// Measured by the block profiler as the single hottest thing during a load:
+// 17.7% of all samples. Unlike inflate this is PURE - no state, no lifetime -
+// so it is the same trivial, safe interception as FnvHashAccelHookCb.
+// The game calls it directly on decompressed data (archive integrity
+// checks), i.e. on top of whatever crc32 work happens inside inflate itself.
+constexpr uint64_t kCrc32Addr = 0x65f6c8;
+
+// One callback for all four - it dispatches on the hook address, the same way
+// QuadGeometryProbeHookCb does, so registration stays a handful of lines.
+void HookCb(uc_engine* uc, uint64_t address, uint32_t size, void* userData);
+
+} // namespace zlib_accel

mpcore/src/main/cpp/game_lifecycle_stubs.cpp

@@ -0,0 +1,82 @@
+// ARM64-only-device prototype: `GameActivityMain`'s native lifecycle/GL
+// callbacks, wired for real (2026-08-29) - see ARM64_TRANSLATION_LAYER.md's
+// "boot the game" follow-up. Each of these forwards into libapp.so's own
+// real implementation (real_native_offsets.h - found via a plain .dynsym
+// dump, not IDA RE, since JNI export names survive stripping) via
+// CallGuestFunction, through the guest JNIEnv bridge (emu/jni_shim.*).
+//
+// `nativeOnPhysicalKeyboardVisibilityChanged` has no real libapp.so
+// implementation (absent from .dynsym - confirmed, not just unresolved by
+// this port) and stays a no-op stub.
+#include <jni.h>
+#include "util/util.h"
+#include "real_native_call.h"
+#include "real_native_offsets.h"
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeOnCreate(JNIEnv* env, jobject thiz) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_ONCREATE_OFFSET);
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeOnDestroy(JNIEnv* env, jobject thiz) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_ONDESTROY_OFFSET);
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeOnMusicPlayerStateChanged(JNIEnv* env, jobject thiz) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_ONMUSICPLAYERSTATECHANGED_OFFSET);
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeOnPause(JNIEnv* env, jobject thiz) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_ONPAUSE_OFFSET);
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeOnRestart(JNIEnv* env, jobject thiz) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_ONRESTART_OFFSET);
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeOnResume(JNIEnv* env, jobject thiz) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_ONRESUME_OFFSET);
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeOnStart(JNIEnv* env, jobject thiz) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_ONSTART_OFFSET);
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeOnStop(JNIEnv* env, jobject thiz) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_ONSTOP_OFFSET);
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeOnOrientationChange(JNIEnv* env, jobject thiz, jint i) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_ONORIENTATIONCHANGE_OFFSET, {(uint32_t)i});
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeOnPhysicalKeyDown(JNIEnv* env, jobject thiz, jint keyCode, jint scanCode) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_ONPHYSICALKEYDOWN_OFFSET, {(uint32_t)keyCode, (uint32_t)scanCode});
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeOnPhysicalKeyUp(JNIEnv* env, jobject thiz, jint i, jint i2) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_ONPHYSICALKEYUP_OFFSET, {(uint32_t)i, (uint32_t)i2});
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeOnPhysicalKeyboardVisibilityChanged(JNIEnv*, jobject, jboolean) {
+    Log("game_lifecycle_stubs: nativeOnPhysicalKeyboardVisibilityChanged() - no real libapp.so "
+        "implementation exists (absent from .dynsym) - staying a no-op");
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeOnPhysicalNavigationVisibilityChanged(JNIEnv* env, jobject thiz, jboolean z) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_ONPHYSICALNAVIGATIONVISIBILITYCHANGED_OFFSET, {(uint32_t)z});
+}
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeRestoreContext(JNIEnv* env, jobject thiz) {
+    return (jboolean)CallRealNative(env, thiz, REAL_GAMEACTIVITY_RESTORECONTEXT_OFFSET);
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeSurfaceChanged(JNIEnv* env, jobject thiz, jobject gl10, jint w, jint h) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_SURFACECHANGED_OFFSET,
+                   {GuestHandleFor(gl10), (uint32_t)w, (uint32_t)h});
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeSurfaceCreated(JNIEnv* env, jobject thiz, jobject gl10, jobject eglConfig) {
+    CallRealNative(env, thiz, REAL_GAMEACTIVITY_SURFACECREATED_OFFSET,
+                   {GuestHandleFor(gl10), GuestHandleFor(eglConfig)});
+}

mpcore/src/main/cpp/game_lifecycle_stubs_extra.cpp

@@ -0,0 +1,51 @@
+// ARM64-only-device prototype: EAIO/StorageDirectory/RunLoop/MogaController
+// natives, wired for real (2026-08-29) - see game_lifecycle_stubs.cpp's own
+// top comment for the mechanism. All confirmed present in libapp.so's own
+// .dynsym (real_native_offsets.h).
+#include <jni.h>
+#include "util/util.h"
+#include "real_native_call.h"
+#include "real_native_offsets.h"
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_EAIO_EAIO_StartupNativeImpl(JNIEnv* env, jobject thiz, jobject assetManager,
+                                         jstring dataPath, jstring filesDirPath, jstring externalPath) {
+    CallRealNative(env, thiz, REAL_EAIO_STARTUP_OFFSET,
+                   {GuestHandleFor(assetManager), GuestHandleFor(dataPath),
+                    GuestHandleFor(filesDirPath), GuestHandleFor(externalPath)});
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_EAIO_EAIO_Shutdown(JNIEnv* env, jclass clazz) {
+    // Shutdown() is @JvmStatic (jclass receiver, not jobject) - the real
+    // guest function itself doesn't care (it never dereferences `thiz` as a
+    // real object here, just needs *some* consistent handle to pass), so
+    // reuse CallRealNative's jobject-shaped helper with the class handle.
+    CallRealNative(env, (jobject)clazz, REAL_EAIO_SHUTDOWN_OFFSET);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_EAMIO_StorageDirectory_StartupNativeImpl(JNIEnv* env, jobject thiz) {
+    CallRealNative(env, thiz, REAL_STORAGEDIR_STARTUP_OFFSET);
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_EAMIO_StorageDirectory_ShutdownNativeImpl(JNIEnv* env, jobject thiz) {
+    CallRealNative(env, thiz, REAL_STORAGEDIR_SHUTDOWN_OFFSET);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_RunLoop_nativeOnRunLoopTick(JNIEnv* env, jobject thiz) {
+    CallRealNative(env, thiz, REAL_RUNLOOP_TICK_OFFSET);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_MogaController_nativeOnKeyEvent(JNIEnv* env, jobject thiz, jobject keyEvent) {
+    CallRealNative(env, thiz, REAL_MOGA_ONKEYEVENT_OFFSET, {GuestHandleFor(keyEvent)});
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_MogaController_nativeOnMotionEvent(JNIEnv* env, jobject thiz, jobject motionEvent) {
+    CallRealNative(env, thiz, REAL_MOGA_ONMOTIONEVENT_OFFSET, {GuestHandleFor(motionEvent)});
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_MogaController_nativeOnStateEvent(JNIEnv* env, jobject thiz, jobject stateEvent) {
+    CallRealNative(env, thiz, REAL_MOGA_ONSTATEEVENT_OFFSET, {GuestHandleFor(stateEvent)});
+}

mpcore/src/main/cpp/game_lifecycle_stubs_extra2.cpp

@@ -0,0 +1,184 @@
+// ARM64-only-device prototype - FMOD (libfmodex.so, not loaded into the
+// emulator - no arm64-v8a build exists at all, see ARM64_TRANSLATION_LAYER.md)
+// stays stubbed. EA Nimble's lifecycle bridge and GameGLSurfaceView's touch
+// forwarders ARE inside libapp.so's own .dynsym and are wired for real
+// (2026-08-29) - see game_lifecycle_stubs.cpp's own top comment.
+// NimbleCppComponentRegistrar$NimbleCppComponent's 6 methods and
+// BaseNativeCallback's 2 are NOT in libapp.so's .dynsym (confirmed, not
+// just unresolved by this port) and stay stubbed too.
+#include <jni.h>
+#include <cstdint>
+#include <cstring>
+#include <set>
+#include <string>
+#include "emu/jni_shim.h"
+#include "util/util.h"
+#include "real_native_call.h"
+#include "real_native_offsets.h"
+
+// ---- FMOD audio bridge (task #67, 2026-09-21) ----
+//
+// Both of these used to `return 0`, silently, on the stated grounds that FMOD
+// was not loaded because no arm64 build exists. That is still true of arm64 -
+// but the game's real ARM32 libfmodex/libfmodevent now run inside the engine
+// as secondary guest images, and both of these symbols are among their
+// exports, so the calls can be forwarded to the real implementations.
+//
+// Why this pair is the whole audio path: FMOD on this Android build does not
+// drive the output device from native code. org/fmod/FMODAudioDevice.java owns
+// an AudioTrack and pulls PCM down through these two methods. Its thread reads
+//
+//     int rate = fmodGetInfo(FMOD_INFO_SAMPLERATE);
+//     if (rate > 0) { ...create the AudioTrack, then loop on fmodProcess... }
+//
+// so a `return 0` from fmodGetInfo alone made that thread give up before the
+// AudioTrack was ever constructed. Nothing downstream could have produced
+// sound regardless of what FMOD itself did.
+// Re-enabled 2026-09-21 once the JNI call epoch became per-thread.
+//
+// These two run on FMODAudioDevice's own AudioTrack thread, and the first
+// attempt aborted the process inside GLThread with "JNI DETECTED ERROR IN
+// APPLICATION: jfieldID was NULL". The first diagnosis - that CallRealNative's
+// SetRealEnv() clobbered a shared JNIEnv - was WRONG: real_env_ was already
+// thread_local, with a lazy AttachCurrentThread fallback.
+//
+// The actual culprit was one line further on. SetRealEnv also calls
+// JniHandleTable::BumpCallEpoch(), and that epoch was a single process-wide
+// counter whose own comment said it invalidates the previous call's local refs
+// "whether or not it's the same thread". So every 100 ms this bridge was
+// invalidating the references GLThread held mid-call. The epoch is per-thread
+// now, which is the more accurate model anyway - a local ref's lifetime is
+// scoped to a native call on its own thread.
+static constexpr bool kEnableFmodAudioBridge = true;
+
+static GuestAddr FmodGuestSymbol(const char* name) {
+    GuestAddr addr = GuestEngine::Instance().LookupSecondaryExport(name);
+    if (!addr) {
+        static std::set<std::string> reported;
+        if (reported.insert(name).second) {
+            Log("fmod_bridge: '%s' is not exported by any loaded guest image - audio stays silent. "
+                "Did libfmodex.so/libfmodevent.so fail to load? (see LoadSiblingLibraries)", name);
+        }
+    }
+    return addr;
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_org_fmod_FMODAudioDevice_fmodGetInfo(JNIEnv* env, jobject thiz, jint info) {
+    if (!kEnableFmodAudioBridge) return 0;
+    static GuestAddr fn = FmodGuestSymbol("Java_org_fmod_FMODAudioDevice_fmodGetInfo");
+    if (!fn) return 0;
+    // Deliberately NOT logged per call: FMODAudioDevice polls this from its
+    // audio thread continuously (1,210 calls in a 40-second run), so a log
+    // line here is a steady drip into a buffer we already lose history to.
+    return (jint)CallRealNative(env, thiz, fn, {(uint32_t)info});
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_org_fmod_FMODAudioDevice_fmodProcess(JNIEnv* env, jobject thiz, jobject buffer) {
+    if (!kEnableFmodAudioBridge) return 0;
+    static GuestAddr fn = FmodGuestSymbol("Java_org_fmod_FMODAudioDevice_fmodProcess");
+    if (!fn || !buffer) return 0;
+
+    // The ByteBuffer came from Java's own allocateDirect, so it lives at a host
+    // address the guest cannot write to - GetDirectBufferAddress would hand
+    // guest FMOD a zero. Bounce through a guest-memory buffer of the same size
+    // instead, exactly as the font fix does for AndroidBitmap_lockPixels, and
+    // copy the rendered PCM back out afterwards.
+    jlong capacity = env->GetDirectBufferCapacity(buffer);
+    void* hostDest = env->GetDirectBufferAddress(buffer);
+    if (capacity <= 0 || !hostDest) {
+        static bool logged = false;
+        if (!logged) {
+            logged = true;
+            Log("fmod_bridge: fmodProcess got a ByteBuffer with no direct address (capacity=%lld) - "
+                "returning silence", (long long)capacity);
+        }
+        return 0;
+    }
+
+    // Allocated once and reused: this runs on the AudioTrack thread at the
+    // audio buffer rate, so per-call allocation would be both wasteful and a
+    // source of jitter. The capacity is fixed by FMOD's DSP buffer settings
+    // and does not change after the device starts, but it is re-checked rather
+    // than assumed.
+    static GuestAddr guestBuf = 0;
+    static uint32_t guestBufSize = 0;
+    static uint32_t guestBufHandle = 0;
+    if (guestBufSize != (uint32_t)capacity) {
+        guestBuf = GuestEngine::Instance().heap().Alloc((uint32_t)capacity);
+        if (!guestBuf) {
+            Log("fmod_bridge: could not allocate a %lld-byte guest audio buffer - silence",
+                (long long)capacity);
+            return 0;
+        }
+        guestBufSize = (uint32_t)capacity;
+        guestBufHandle = JniShim::Instance().NewGuestBackedDirectBuffer(
+            GuestEngine::Instance(), guestBuf, guestBufSize);
+        Log("fmod_bridge: audio bounce buffer ready - %u bytes at guest 0x%x (handle %u)",
+            guestBufSize, guestBuf, guestBufHandle);
+    }
+    if (!guestBufHandle) return 0;
+
+    memset(GuestEngine::Instance().G2H(guestBuf), 0, guestBufSize);
+    jint r = (jint)CallRealNative(env, thiz, fn, {guestBufHandle});
+    memcpy(hostDest, GuestEngine::Instance().G2H(guestBuf), guestBufSize);
+    return r;
+}
+
+#define NIMBLE_COMPONENT_STUB(name)                                                                     \
+    extern "C" JNIEXPORT void JNICALL                                                                    \
+    Java_com_ea_nimble_bridge_NimbleCppComponentRegistrar_00024NimbleCppComponent_##name(JNIEnv*, jobject) { \
+        Log("game_lifecycle_stubs_extra2: NimbleCppComponent." #name "() - no-op "                       \
+            "(no real libapp.so implementation - absent from .dynsym)");                                 \
+    }
+NIMBLE_COMPONENT_STUB(cleanup)
+NIMBLE_COMPONENT_STUB(restore)
+NIMBLE_COMPONENT_STUB(resume)
+NIMBLE_COMPONENT_STUB(setup)
+NIMBLE_COMPONENT_STUB(suspend)
+NIMBLE_COMPONENT_STUB(teardown)
+#undef NIMBLE_COMPONENT_STUB
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_nimble_bridge_BaseNativeCallback_nativeCallback(JNIEnv*, jclass, jint, jobjectArray) {
+    Log("game_lifecycle_stubs_extra2: BaseNativeCallback.nativeCallback() - no-op");
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_nimble_bridge_BaseNativeCallback_nativeFinalize(JNIEnv*, jclass, jint) {}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_nimble_bridge_NimbleCppApplicationLifeCycle_onApplicationLaunch(JNIEnv* env, jobject thiz, jobject map) {
+    CallRealNative(env, thiz, REAL_NIMBLE_ON_APP_LAUNCH_OFFSET, {GuestHandleFor(map)});
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_nimble_bridge_NimbleCppApplicationLifeCycle_onApplicationQuit(JNIEnv* env, jobject thiz) {
+    CallRealNative(env, thiz, REAL_NIMBLE_ON_APP_QUIT_OFFSET);
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_nimble_bridge_NimbleCppApplicationLifeCycle_onApplicationResume(JNIEnv* env, jobject thiz, jobject map) {
+    CallRealNative(env, thiz, REAL_NIMBLE_ON_APP_RESUME_OFFSET, {GuestHandleFor(map)});
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_nimble_bridge_NimbleCppApplicationLifeCycle_onApplicationSuspend(JNIEnv* env, jobject thiz) {
+    CallRealNative(env, thiz, REAL_NIMBLE_ON_APP_SUSPEND_OFFSET);
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_nimble_bridge_NimbleCppApplicationLifeCycle_onUpdateLaunchMethod(JNIEnv* env, jobject thiz, jobject map) {
+    CallRealNative(env, thiz, REAL_NIMBLE_ON_UPDATE_LAUNCH_METHOD_OFFSET, {GuestHandleFor(map)});
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameGLSurfaceView_nativeTouchPadEvent(JNIEnv* env, jobject thiz, jint i, jint i2, jfloat f, jfloat f2) {
+    uint32_t fBits, f2Bits;
+    memcpy(&fBits, &f, 4);
+    memcpy(&f2Bits, &f2, 4);
+    CallRealNative(env, thiz, REAL_GLSURFACEVIEW_TOUCHPAD_OFFSET, {(uint32_t)i, (uint32_t)i2, fBits, f2Bits});
+}
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameGLSurfaceView_nativeTouchScreenEvent(JNIEnv* env, jobject thiz, jint i, jint i2, jfloat f, jfloat f2) {
+    uint32_t fBits, f2Bits;
+    memcpy(&fBits, &f, 4);
+    memcpy(&f2Bits, &f2, 4);
+    CallRealNative(env, thiz, REAL_GLSURFACEVIEW_TOUCHSCREEN_OFFSET, {(uint32_t)i, (uint32_t)i2, fBits, f2Bits});
+}

mpcore/src/main/cpp/main.cpp

@@ -5,6 +5,7 @@
 #include <android/log.h>
 #include <jni.h>
 #include "main.h"
+#include "crash_handler.h"
 #include "util/util.h"
 #include <unistd.h>
 #include <unwind.h>
@@ -17,27 +18,332 @@
 #include "util/armhook.h"
 #include "util/armhooks.h"
 #include "game_events.h"
-#include "lan_event_injection.h"
-#include "opponent_substitution.h"
-#include "cop_traffic_disable.h"
+#include "emu/guest_engine.h"
+#include "emu/ostream_repro_test.h"
+#include "emu/guest_trace.h"
+#include "emu/tcg_bench.h"
+#include "emu/guest_fn.h"
+#include "emu/import_shims.h"
+#include "emu/pthread_shim.h"
+#include "emu/jni_shim.h"
+#include "emu/gles_shim.h"
+#include "emu/libc_shims.h"
+#include "emu/rtti_shims.h"
+#include "emu/dyncast_fastpath.h"
+#include "emu/fmod_shims.h"
+#include "emu/profiler.h"
+#include "real_native_offsets.h"
+// ---- ARM64-only-device prototype (2026-08-19): the LAN event-injection
+// subsystem (lan_event_injection.h + its own nested car_selection.h/
+// mod_slot_tracking.h/crash_workarounds.h includes) is DELIBERATELY NOT
+// wired into this emulated build - see ARM64_TRANSLATION_LAYER.md and this
+// session's own notes. Short version: every function pointer it resolves
+// (GetOutputNode, ResolveHandle, HashInsert, ...) now needs to route
+// through GuestFn/CallGuestFunction instead of a raw C call, which is a
+// small, mechanical change - but several of its call sites pass a pointer
+// to a LOCAL HOST STACK VARIABLE as an "out parameter" the guest function
+// writes into (e.g. ResolveHandle(&res, ctx, &key), HashInsert(&insertResult,
+// ...)) - Unicorn's guest code can only read/write memory inside the mapped
+// guest region, not arbitrary host process memory, so each of those call
+// sites needs its own guest-scratch-buffer marshaling (copy in, call,
+// copy out), individually, by hand. That's real, bounded work, but doing
+// it blind - with no device or even a desktop harness available for THIS
+// subsystem's own live-tuned wall-clock timing assumptions - risked
+// shipping quietly-wrong behavior across ~30 call sites with zero way to
+// catch a mistake. Left as source (untouched) for a follow-up session with
+// real testing available, rather than force a rushed port now. The two
+// self-contained hooks below (BuildTrackScenePath, MapScreenCtor) have no
+// out-parameter calls at all, so they ARE fully ported and are the real
+// end-to-end proof this mechanism works.
+// #include "lan_event_injection.h"
+//
+// Branch merge (2026-09-22): opponent_substitution.h and cop_traffic_disable.h
+// landed from the native32/lan-event-injection-poc branch, where they were
+// built and live-confirmed against a real dlopen'd libapp.so - proven
+// correct, but every one of their hooks resolves and calls raw
+// "libapp_base + OFFSET" function pointers directly (this file's own
+// InstallArmTrampolineHook pattern), the exact same shape as
+// lan_event_injection.h's un-ported call sites above. On THIS build there is
+// no real ARM32 code at that address to jump to - only Unicorn-backed guest
+// memory - so including these unmodified would not just misbehave, it would
+// jump the host CPU into data and crash immediately. Left as source
+// (untouched, not included) for the same follow-up porting session as
+// lan_event_injection.h, not wired in here.
+// #include "opponent_substitution.h"
+// #include "cop_traffic_disable.h"
 
 void* libapp_base = NULL;
 
-static int find_lib_callback(struct dl_phdr_info* info, size_t size, void* data) {
-    if (strstr(info->dlpi_name, "libapp.so")) {
-        libapp_base = (void*)info->dlpi_addr;
-        LOGD("Found libapp.so at base: 0x%08X", (uintptr_t)libapp_base);
-        return 1; // Останавливаем перебор
-    }
-    return 0;
-}
-
-bool get_libapp_base() {
-    dl_iterate_phdr(find_lib_callback, NULL);
-    if (!libapp_base) {
-        Log("libapp.so not found in memory!");
+// Loads libapp.so through the embedded ARM32 CPU-emulation core instead of
+// finding it via dl_iterate_phdr - there is no real dlopen'd libapp.so to
+// find in this build; see ARM64_TRANSLATION_LAYER.md. `path` is a real
+// filesystem path Kotlin extracts the bundled asset to before calling this
+// (see MultiplayerCore.loadEmulatedLibapp / GameActivityMain.kt) since
+// JNI_OnLoad itself has no Context/AssetManager access.
+bool LoadEmulatedLibapp(const char* path, JNIEnv* env, jobject thiz) {
+    // One-shot, throwaway benchmark - see tcg_bench.h's own comment. Remove
+    // once the "is Unicorn/TCG itself the bottleneck" question is answered.
+    RunTcgBenchmark();
+    GuestEngine& engine = GuestEngine::Instance();
+    // EnableProfiling() (see profiler.h) used to be called unconditionally
+    // here for the "why did onCreate take 115s" investigation
+    // (ARM64_TRANSLATION_LAYER.md, 2026-09-01). Confirmed live (2026-09-05,
+    // "100x native" investigation) that this - and the two other
+    // UC_HOOK_BLOCK diagnostics it gates in guest_engine.cpp
+    // (TraceRingHookCb, LiveTraceRingHookCb) - fire on literally every
+    // basic block executed anywhere in the guest binary, for the whole run:
+    // a real, avoidable per-block tax, independent of and on top of the
+    // separate uc_emu_stop()-per-shim-call fix. Left disabled by default;
+    // uncomment when actually debugging a fault, stall, or hot-path
+    // question that needs the block profiler/trace ring.
+    // TEMPORARILY ENABLED 2026-09-19 for ONE capture (task #42). Three
+    // separate load-time theories - log volume, per-draw glGetIntegerv, and
+    // emulated zlib - each turned out to be real but not dominant: the zlib
+    // interception demonstrably moved 156MB of decompression off the
+    // emulator and the load barely moved. Stop theorising, measure.
+    // MUST be commented out again after the capture - this is a
+    // UC_HOOK_BLOCK over the whole image and leaving it on has already
+    // caused a user-visible regression twice, as the comment above records.
+    // Capture done 2026-09-19, profiler switched back off (see the warning
+    // above - a UC_HOOK_BLOCK over the whole image must never be left on).
+    // What it found, over 177,881 samples across 6,477 distinct blocks:
+    //   crc32            (sub_65F6C8)  17.7%  -> now served by host zlib
+    //   name lookup      (sub_4F3704)  18.8%  -> linear strcmp scan, task #42
+    //   glClear's caller (sub_567BD4)   3.8%
+    // i.e. no single dominant hotspot beyond those two; the rest is a long
+    // tail of ordinary guest code, which is why the three earlier
+    // "obvious" load-time theories each moved the needle so little.
+    // EnableProfiling();
+    StartProfileDumpThread();
+    // 2026-09-06: full block+JNI-call trace for the "where does the
+    // emulated engine's execution first diverge from A9's" investigation
+    // (see guest_trace.h and ARM64_TRANSLATION_LAYER.md). Left ENABLED
+    // unconditionally here for one capture session and caused a real,
+    // user-noticed performance regression (clock_gettime()+gettid() on
+    // every single executed block, on top of the already-fixed
+    // uc_emu_stop() cost) - the exact same "always-on UC_HOOK_BLOCK
+    // diagnostic" mistake EnableProfiling()'s own comment above already
+    // documents and fixed once. Disabled by default now, like
+    // EnableProfiling() - uncomment only while actively capturing a new
+    // guest/JNI trace, never leave it on for an ordinary test run.
+    // EnableFullGuestTrace();
+    // StartGuestTraceDumpThread();
+    // See gles_shim.h's own comment - "nothing renders past the splash"
+    // investigation.
+    StartGlesCounterDumpThread();
+    // See guest_engine.h's own comment - periodic live instruction trace for
+    // the same investigation, once RegisterNatives was ruled out.
+    StartLiveTraceDumpThread();
+    // See jni_shim.h's own comment: FindClass only sees app classes when
+    // called from the thread that loaded the native library - cache the
+    // real ClassLoader now (main thread, from a real app object) so later
+    // FindClass calls from other threads (e.g. the real engine's own
+    // GLThread) have a working fallback.
+    JniShim::Instance().CacheClassLoader(env, thiz);
+    RegisterCoreImportShims(engine);
+    // Must run BEFORE RegisterPthreadImportShims - libc_shims.cpp registers
+    // a placeholder "pthread_join" purely so the symbol is never silently
+    // unresolved; pthread_shim.cpp's REAL join implementation needs to
+    // register after it and win (RegisterImportShim is last-registration-
+    // wins, see guest_engine.cpp).
+    RegisterLibcImportShims(engine);
+    RegisterPthreadImportShims(engine);
+    RegisterGlesImportShims(engine);
+    RegisterRttiImportShims(engine);
+    // Must follow RegisterRttiImportShims: the fast path's fallback resolves
+    // "__dynamic_cast_slowpath", which that call registers.
+    RegisterDynamicCastFastPath(engine);
+    RegisterFmodImportShims(engine);
+    // Must be registered BEFORE LoadImage() - SetupRttiDataSymbols needs to
+    // run after MapSegments (for AllocPermanent) but strictly before
+    // ProcessRelocations resolves any GOT slot referencing these typeinfo
+    // symbols; see GuestEngine::RegisterDataSymbolSetup's own comment for
+    // why this is a callback rather than a direct call here.
+    engine.RegisterDataSymbolSetup(&SetupRttiDataSymbols);
+    engine.RegisterDataSymbolSetup(&SetupLibcDataSymbols);
+    if (!engine.LoadImage(path)) {
+        Log("LoadEmulatedLibapp: GuestEngine::LoadImage(%s) failed", path);
         return false;
     }
+    // Every existing "(uintptr_t)libapp_base + OFFSET" expression across
+    // this codebase (car_selection.h, crash_workarounds.h, and the two
+    // hooks below) now resolves to a real host pointer into the emulator's
+    // own guest-backing memory, unchanged - see GuestEngine's class comment
+    // for why this identity mapping is possible.
+    libapp_base = engine.image_host_base();
+
+    // libapp.so's own real JNI_OnLoad (found via .dynsym, same as every
+    // other offset in real_native_offsets.h) - statically-linked engines
+    // commonly do extra runtime registration here beyond what the ELF's own
+    // .init_array (run by GuestEngine::ProcessRelocations, right after
+    // relocations complete - see its own comment) covers. Calling it needs
+    // a guest-visible JavaVM* (see jni_shim.h's own comment).
+    JniShim::Instance().SetRealEnv(env);
+    GuestAddr guestVm = JniShim::Instance().BuildGuestJavaVM(engine);
+    uint32_t jniOnLoadResult = engine.CallGuestFunction(REAL_JNI_ONLOAD_OFFSET, guestVm, 0);
+    Log("LoadEmulatedLibapp: real JNI_OnLoad returned 0x%x", jniOnLoadResult);
+
+    // Synthetic benchmark/unit-test calls (RunTcgBenchmarkInRealContext,
+    // RunCalleeSavedRegisterTest) removed 2026-09-16 - their questions are
+    // answered (see ARM64_TRANSLATION_LAYER.md): TCG itself isn't the
+    // bottleneck, and the import-stub dispatch path preserves callee-saved
+    // registers.
+    //
+    // RunReentrantCallRegisterTest call removed again 2026-09-16 (same day,
+    // second removal) after confirming PASS on-device: once
+    // GuestEngine::CreateConfiguredEngine/GetOrCreateNestedEngine
+    // (guest_engine.h/.cpp) gave depth>0 CallGuestFunction calls their own
+    // uc_engine* instead of re-entering the depth-0 one mid-uc_emu_start(),
+    // this test completed cleanly (stub_hit=yes, r4-r7 all OK) instead of
+    // hanging forever - and the app kept running afterward, with real
+    // reentrant calls (depth=1, even depth=2) happening naturally on other
+    // threads with no hang. Test function stays in tcg_bench.h/.cpp for
+    // reuse if this area is ever suspected again.
+
+    // 2026-09-05/06 (ARM64_TRANSLATION_LAYER.md "PERFORMANCE tier"
+    // investigation): sub_547B40 computes a device "performance tier" from
+    // RAM/a Java-side getPerformanceScore() heuristic/GPU-renderer-string
+    // and caches it in these two globals (byte_ADFD0C = "already computed",
+    // dword_ADFD10 = the value). Confirmed live via a native32/armeabi-v7a
+    // reference build on the Galaxy A9 (real hardware, no emulation): real
+    // devices settle on "High" (tier 23), reached via a SECOND call once the
+    // GL renderer string is known (the first, GPU-string-less call takes an
+    // early-return path that doesn't mark the cache as final, matching the
+    // observed "Tier = Higest" then "Tier = High" sequence in the real
+    // device's own log). Pre-seeding 23 here matches that real behavior -
+    // worth doing regardless, but NOT by itself sufficient to avoid the
+    // crash below (confirmed live: forcing 23 hits the exact same crash as
+    // the unforced/default path, just via a different switch case in
+    // sub_3A4E5C - the real bug is the dword_ADCAA0 issue documented at
+    // this function's next fix, not which tier gets chosen). Placed AFTER
+    // JNI_OnLoad/BuildGuestJavaVM (moved 2026-09-06 - see this function's
+    // own next comment for why ordering here matters).
+    {
+        constexpr GuestAddr kPerfTierCachedFlagAddr = 0xADFD0Cu;  // byte_ADFD0C
+        constexpr GuestAddr kPerfTierCachedValueAddr = 0xADFD10u; // dword_ADFD10
+        constexpr uint32_t kHighTier = 23; // sub_547B40's own tier constant for "High" - confirmed on real hardware
+        uint32_t tierValue = kHighTier;
+        uint8_t alreadyCached = 1;
+        memcpy(engine.G2H(kPerfTierCachedValueAddr), &tierValue, sizeof(tierValue));
+        memcpy(engine.G2H(kPerfTierCachedFlagAddr), &alreadyCached, sizeof(alreadyCached));
+        Log("LoadEmulatedLibapp: pre-seeded sub_547B40's performance-tier cache to High (23) - "
+            "see this call site's own comment");
+    }
+    // 2026-09-06 (same investigation, real root cause): dword_ADCAA0 is
+    // libapp.so's own global "debug log stream" object (used from 200+
+    // call sites across the whole binary, e.g. every "Foo = bar" line seen
+    // in logcat under tag "info"/"trace"). Its C++ constructor DOES run
+    // (via .init_array - confirmed live: dword_ADCAA0's vtable pointer and
+    // "good" flag at +76 are set up correctly), but the embedded streambuf-
+    // shaped sub-object's OWN internal pointer (read by sub_3EA194 as "v17",
+    // then called through via vtable+48 while converting a wide string to
+    // UTF-8 for logging) is left null - and nothing in this engine ever
+    // populates it afterward, unlike on real hardware (confirmed via the
+    // same Galaxy A9 native32 reference build: the identical "PERFORMANCE -
+    // level = 3" log line - same function, same wide-string-conversion path
+    // - completes successfully there and the game continues straight into
+    // SoundManager init). Since real devices reach this through machinery
+    // this project doesn't emulate (whatever real ART/libc++ construction
+    // path finishes attaching this sub-object) rather than through anything
+    // under our control, the pragmatic fix - matching this file's existing
+    // "pre-seed a real, reasonable state instead of tracing the original
+    // construction path to its end" precedent for the tier cache above - is
+    // to give that field a genuine, safe, callable vtable whose slots all
+    // just return 0 (same generic pattern rtti_shims.cpp's ctype<char>/
+    // num_put<char> facets already use for library objects this project
+    // doesn't fully reimplement), instead of leaving it null. Placed AFTER
+    // BuildGuestJavaVM/BuildGuestJNIEnv's own AllocPermanent/AllocCodeStub
+    // calls (moved 2026-09-06): confirmed live that placing this block
+    // BEFORE them let its allocations shift the control/misc-stub arena
+    // layout under the VM/JNIEnv function tables built later, corrupting a
+    // JavaVM slot (AttachCurrentThread) that a background pthread_create'd
+    // thread then jumped through - moving this fix to run strictly after
+    // every other subsystem's own one-time setup calls avoids stepping on
+    // arena layout anything else still needs to allocate.
+    {
+        // sub_3EA194 (called with a1 = dword_ADCAA0+224, the embedded
+        // streambuf sub-object) computes its crashing pointer as:
+        //   innerVtable = *(a1)                    // the streambuf's OWN vtable ptr
+        //   off         = *(innerVtable - 12)       // real Itanium offset-to-top-style value baked into that vtable
+        //   v17         = *(a1 + off + 24)          // THIS is the null field - not a fixed "+248" offset
+        // Confirmed live this session that assuming off==0 (a naive
+        // "224+24=248" guess) was WRONG - that write didn't reach the real
+        // v17 storage location and the crash persisted identically. Read
+        // `off` from the real, already-constructed vtable instead of
+        // assuming it, so the fix lands on the actual field regardless of
+        // this class's real (compiler-chosen) layout.
+        constexpr GuestAddr kAdcaa0Addr = 0xADCAA0u;
+        constexpr GuestAddr kStreamBufAddr = kAdcaa0Addr + 224u;
+        uint32_t innerVtable = 0;
+        memcpy(&innerVtable, engine.G2H(kStreamBufAddr), 4);
+        uint32_t off = 0;
+        if (innerVtable >= 12) memcpy(&off, engine.G2H(innerVtable - 12), 4);
+        GuestAddr v17Addr = kStreamBufAddr + off + 24u;
+        Log("LoadEmulatedLibapp: dword_ADCAA0 streambuf vtable=0x%x off=0x%x -> v17 storage at 0x%x "
+            "(current value 0x%x)",
+            innerVtable, off, v17Addr, *(uint32_t*)engine.G2H(v17Addr));
+
+        constexpr int kNoOpVtableSlots = 16; // generous - the confirmed-needed slot is #12 (byte offset 48)
+        GuestAddr vtable = engine.AllocPermanent((uint32_t)kNoOpVtableSlots * 4);
+        for (int i = 0; i < kNoOpVtableSlots; i++) {
+            GuestAddr stub = engine.AllocCodeStub(
+                [](uc_engine* uc, uint64_t, uint32_t, void*) {
+                    uint32_t zero = 0;
+                    uc_reg_write(uc, UC_ARM_REG_R0, &zero);
+                },
+                nullptr);
+            if (vtable && stub) memcpy(engine.G2H(vtable + (uint32_t)i * 4), &stub, 4);
+        }
+        GuestAddr obj = engine.AllocPermanent(4);
+        if (obj && vtable) memcpy(engine.G2H(obj), &vtable, 4);
+        if (obj) {
+            memcpy(engine.G2H(v17Addr), &obj, 4);
+            Log("LoadEmulatedLibapp: pre-seeded dword_ADCAA0's real v17 field (0x%x) with a safe "
+                "no-op vtable object (0x%x) - see this call site's own comment", v17Addr, obj);
+        } else {
+            Log("LoadEmulatedLibapp: failed to allocate the dword_ADCAA0 v17 no-op object");
+        }
+    }
+
+    // Temporarily wired in (2026-09-17, ARM64_TRANSLATION_LAYER.md - the
+    // 0x3d3d3d3d heap-overflow chase). Tests whether "long first write
+    // forcing SSO->heap transition, then a real nested function call
+    // writing more into the same stream" alone reproduces the corruption in
+    // total isolation from the real game. Remove once this question is
+    // answered, same discipline as every other one-shot test call in this
+    // function.
+    RunOstreamAssemblyNestedReproTest(engine);
+
+    // RunOstreamAssemblyReproTest call removed 2026-09-16 - its question is
+    // answered (see ARM64_TRANSLATION_LAYER.md's "isolated
+    // std::ostringstream repro" entry): a real, standalone armeabi-v7a
+    // artifact (ostream_repro/, GuestEngine::LoadSecondaryImage) exercising
+    // the exact same write-then-extract std::ostringstream pattern as the
+    // real game's sub_4702D8/sub_27160C came back PASS, twice, with zero
+    // unresolved-import noise in either run - extracted content matched
+    // exactly what was written (len=49, retVal=49). This rules OUT a
+    // general ostringstream/basic_stringbuf<char>::str()-extraction bug in
+    // GuestEngine itself as the cause of the real game's empty-shader-
+    // source symptom; whatever's actually wrong is specific to libapp.so's
+    // own state/control flow reaching sub_4702D8, not this engine's
+    // translation of the C++ runtime mechanism in general. Same "remove
+    // spent diagnostics once their question is answered" discipline as the
+    // RunCalleeSavedRegisterTest/RunReentrantCallRegisterTest removal note
+    // above - the infrastructure (GuestEngine::LoadSecondaryImage,
+    // emu/ostream_repro_test.{h,cpp}, ostream_repro/) stays in the tree,
+    // only this one-shot call site is gone.
+
+    // RunStackArgMarshalingTest/RunSequentialCallStateLeakTest calls
+    // removed 2026-09-16 - both questions answered PASS (see
+    // ARM64_TRANSLATION_LAYER.md): argCount>4 stack-marshaled arguments
+    // arrive correctly (all 8 of 8 args, register- and stack-passed alike),
+    // and three sequential (non-reentrant) calls through the same
+    // AllocCodeStub-dispatched stub show zero cross-call state leakage.
+    // Same "remove spent diagnostics once their question is answered"
+    // discipline as every other synthetic-test removal note in this
+    // function - the test functions themselves stay in tcg_bench.h/.cpp
+    // for reuse if this area is ever suspected again.
+
     return true;
 }
 int (*sub_4087CC)() = nullptr;
@@ -84,8 +390,7 @@ using namespace std;
 // position-independent, safe to relocate into the trampoline as-is).
 #define BUILDTRACKSCENEPATH_OFFSET 0x2a8424
 
-typedef int (*BuildTrackScenePathFn)(void* raceLoaderTask);
-static BuildTrackScenePathFn orig_BuildTrackScenePath = nullptr;
+static GuestFn<int, void*> orig_BuildTrackScenePath;
 
 // Deliberately different from any real event's track, so a successful
 // override is visually unmistakable. region3/colorado was tried first and
@@ -137,43 +442,18 @@ int Hook_BuildTrackScenePath(void* a1) {
     return orig_BuildTrackScenePath(a1);
 }
 
+// Ported onto GuestEngine (2026-08-19): same target offset, same
+// precondition (position-independent 2-instruction prologue, already
+// verified live-byte-matched against the real libapp.so this session - see
+// scratchpad/spike_load.py), same trampoline TECHNIQUE (verbatim copy of
+// the displaced instructions + jump back to target+8) - it now just builds
+// that trampoline in Unicorn-backed guest memory and is invoked via
+// CallGuestFunction instead of live byte-patching a real dlopen'd library.
+// See guest_engine.h/guest_fn.h for the mechanism.
 static bool InstallBuildTrackScenePathHook() {
-    uintptr_t target = (uintptr_t)libapp_base + BUILDTRACKSCENEPATH_OFFSET;
-    uint32_t* target32 = (uint32_t*)target;
-
-    void* tramp = mmap(nullptr, (size_t)getpagesize(), PROT_READ | PROT_WRITE | PROT_EXEC,
-                        MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
-    if (tramp == MAP_FAILED) {
-        Log("BuildTrackScenePath hook: mmap trampoline failed");
-        return false;
-    }
-
-    uint32_t* tramp32 = (uint32_t*)tramp;
-    // Relocate the 2 displaced original ARM instructions verbatim (both
-    // confirmed position-independent: plain PUSH and ADD, no PC-relative
-    // addressing), then jump back into the function body past them.
-    tramp32[0] = target32[0];
-    tramp32[1] = target32[1];
-    tramp32[2] = 0xE51FF004; // LDR PC, [PC, #-4]
-    tramp32[3] = (uint32_t)(target + 8);
-    orig_BuildTrackScenePath = (BuildTrackScenePathFn)tramp;
-
-    uintptr_t page = target & ~((uintptr_t)getpagesize() - 1);
-    if (mprotect((void*)page, (size_t)getpagesize(), PROT_READ | PROT_WRITE | PROT_EXEC) != 0) {
-        Log("BuildTrackScenePath hook: mprotect target failed: %s", strerror(errno));
-        return false;
-    }
-
-    target32[0] = 0xE51FF004; // LDR PC, [PC, #-4]
-    // &Hook_BuildTrackScenePath has bit0 set (Thumb-compiled mpcore code),
-    // triggering the ARM->Thumb interworking switch on load into PC.
-    target32[1] = (uint32_t)(uintptr_t)&Hook_BuildTrackScenePath;
-
-    __builtin___clear_cache((char*)target, (char*)(target + 8));
-    __builtin___clear_cache((char*)tramp, (char*)tramp + 16);
-
-    Log("Installed RaceLoaderTask_BuildTrackScenePath hook at %p, trampoline=%p", (void*)target, tramp);
-    return true;
+    orig_BuildTrackScenePath = InstallTrampolineHook(
+        BUILDTRACKSCENEPATH_OFFSET, &Hook_BuildTrackScenePath, "RaceLoaderTask_BuildTrackScenePath hook");
+    return (bool)orig_BuildTrackScenePath;
 }
 
 // ---- MapScreen constructor trace hook (temporary, RE discovery only) ----
@@ -186,8 +466,7 @@ static bool InstallBuildTrackScenePathHook() {
 // (found earlier, offsets +0x44.."+0x50") into real screen pixels.
 #define MAPSCREEN_CTOR_OFFSET 0x1781BC
 
-typedef void* (*MapScreenCtorFn)(void* a1);
-static MapScreenCtorFn orig_MapScreenCtor = nullptr;
+static GuestFn<void*, void*> orig_MapScreenCtor;
 void* g_mapScreenInstance = nullptr;
 
 void* Hook_MapScreenCtor(void* a1) {
@@ -197,41 +476,12 @@ void* Hook_MapScreenCtor(void* a1) {
     return result;
 }
 
+// Ported onto GuestEngine (2026-08-19) - see InstallBuildTrackScenePathHook's
+// own comment just above for the mechanism; identical technique.
 static bool InstallMapScreenCtorTraceHook() {
-    uintptr_t target = (uintptr_t)libapp_base + MAPSCREEN_CTOR_OFFSET;
-    uint32_t* target32 = (uint32_t*)target;
-
-    // Confirmed ARM-mode, position-independent prologue this session
-    // (PUSH {R4-R11,LR}; ADD R11,SP,#0x1C), same trampoline pattern as the
-    // other hooks in this file.
-    void* tramp = mmap(nullptr, (size_t)getpagesize(), PROT_READ | PROT_WRITE | PROT_EXEC,
-                        MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
-    if (tramp == MAP_FAILED) {
-        Log("MapScreen ctor hook: mmap trampoline failed");
-        return false;
-    }
-
-    uint32_t* tramp32 = (uint32_t*)tramp;
-    tramp32[0] = target32[0];
-    tramp32[1] = target32[1];
-    tramp32[2] = 0xE51FF004; // LDR PC, [PC, #-4]
-    tramp32[3] = (uint32_t)(target + 8);
-    orig_MapScreenCtor = (MapScreenCtorFn)tramp;
-
-    uintptr_t page = target & ~((uintptr_t)getpagesize() - 1);
-    if (mprotect((void*)page, (size_t)getpagesize(), PROT_READ | PROT_WRITE | PROT_EXEC) != 0) {
-        Log("MapScreen ctor hook: mprotect target failed: %s", strerror(errno));
-        return false;
-    }
-
-    target32[0] = 0xE51FF004; // LDR PC, [PC, #-4]
-    target32[1] = (uint32_t)(uintptr_t)&Hook_MapScreenCtor;
-
-    __builtin___clear_cache((char*)target, (char*)(target + 8));
-    __builtin___clear_cache((char*)tramp, (char*)tramp + 16);
-
-    Log("Installed MapScreen ctor trace hook at %p, trampoline=%p", (void*)target, tramp);
-    return true;
+    orig_MapScreenCtor = InstallTrampolineHook(
+        MAPSCREEN_CTOR_OFFSET, &Hook_MapScreenCtor, "MapScreen ctor trace hook");
+    return (bool)orig_MapScreenCtor;
 }
 
 // Flip to false to run the game completely unmodified (e.g. to capture a
@@ -255,13 +505,28 @@ static bool InstallMapScreenCtorTraceHook() {
 // this PoC toggle should only be flipped on deliberately, for a specific
 // track-substitution test, not left on as the default running state.
 static constexpr bool kEnableTrackSubstitutionHook = false;
-static constexpr bool kEnableLanEventInjectionHook = true;
 static constexpr bool kEnableMapScreenCtorTraceHook = false; // TEMP: isolating a reproducible SIGSEGV, see PROGRESS.md
-// See ANALYSIS.md §6ff/§6gg: prevents a QA-only "Soak Test" auto-race feature
-// from eventually crashing the process on entries our injection adds to the
-// prefab cache. Independent of kEnableLanEventInjectionHook so it can be kept
-// on even if injection itself is toggled off for testing.
-static constexpr bool kEnableSoakTestDisableHook = true;
+
+// JNI_OnLoad only sets up the (unaffected, host-side-only) GameEvents JNI
+// bridge now - loading libapp.so and installing hooks against it needs a
+// real filesystem path to the extracted asset (see LoadEmulatedLibapp's own
+// comment), which JNI_OnLoad has no reliable way to obtain on its own
+// (no Context/AssetManager access at this point). See
+// Java_..._MultiplayerCore_loadEmulatedLibapp below for where that now happens.
+// extern "C" is NOT optional here: without it the name is C++-mangled and the
+// JVM cannot find it by its JNI name. The first version omitted it, and the
+// only symptom was "No implementation found" at runtime - which looked exactly
+// like a load-order problem and cost a wrong fix before the symbol table was
+// actually read.
+extern "C" JNIEXPORT void JNICALL
+Java_com_ea_ironmonkey_GameActivityMain_nativeInstallCrashHandler(JNIEnv* env, jobject,
+                                                                  jstring dir, jstring buildStamp) {
+    const char* d = dir ? env->GetStringUTFChars(dir, nullptr) : nullptr;
+    const char* b = buildStamp ? env->GetStringUTFChars(buildStamp, nullptr) : nullptr;
+    InstallCrashHandler(d, b);
+    if (d) env->ReleaseStringUTFChars(dir, d);
+    if (b) env->ReleaseStringUTFChars(buildStamp, b);
+}
 
 // cont.69/70: subtask 2.1 diagnostic pass - logs OpponentCollection's built
 // Opponent vector and StreetRaceStartingGrid's own placement-vector argument
@@ -279,105 +544,67 @@ JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void* reserved) {
     } else {
         Log("JNI_OnLoad: GetEnv failed, GameEvents bridge not initialised");
     }
-
-    if (get_libapp_base()) {
-        if (kEnableTrackSubstitutionHook) {
-            InstallBuildTrackScenePathHook();
-        }
-        if (kEnableLanEventInjectionHook) {
-            InstallMapTrackHandleEventHook();
-        }
-        if (kEnableSoakTestDisableHook) {
-            InstallSoakTestDisableHook();
-        }
-        if (kEnableOpponentGridDiagnosticHooks) {
-            InstallOpponentCollectionPopulateHook();
-            InstallStreetRaceGridPlaceHook();
-        }
-        InstallCopSpawnSchedulerSkipHook();
-        InstallRaceEventTrafficCarCountHook();
-        InstallTrafficCarSpawnerZeroHook();
-        InstallTrafficResetLineSkipHook();
-        InstallTrafficCarControllerSkipHook();
-        InstallCarResetOnceOnlyHook();
-        if (kEnableMapScreenCtorTraceHook) {
-            InstallMapScreenCtorTraceHook();
-        }
-        InstallCopSoundsTickSkipHook();
-        // cont.67 CONFIRMED ROOT CAUSE, permanently disabled: this hook made
-        // GetComponentName (sub_240548) unconditionally return an empty-string
-        // sentinel for EVERY call, not just the null-input crash case its own
-        // original comment described (cont.29/30 - a narrow SIGSEGV while
-        // triggering our synthetic LAN test event's own car-select flow).
-        // Live-bisected this session against a real, user-reported regression:
-        // real races completed and granted cash/SP correctly, but the
-        // per-event "medal earned" persistent record (read by
-        // MapTrack::AddEvent/sub_369AB0 via sub_77B70/sub_251188/sub_2515D0/
-        // sub_250F34 and a reflective "medal" property - feeds the
-        // street-completion-% badge on the map) was never written, on the
-        // player's very first tutorial/career race. Decompiling this hook's
-        // only relevant caller chain found sub_240294 does NOT just log
-        // GetComponentName's result for a debug label as originally assumed -
-        // it WRITES it into a named-cache-context object's own +8 field (the
-        // same kind of cache-context, via sub_7566C, that the medal-lookup
-        // chain also resolves through), and sub_240294 is itself called from
-        // sub_17A99C, the same real map-event-processing function this
-        // project's own FireEventOutput uses. With every hook EXCEPT this one
-        // installed, medal recording worked correctly live (confirmed twice);
-        // with this one also installed, it silently failed every time -
-        // isolating it as the sole cause. Left declared/installable below in
-        // case the original narrow crash needs revisiting, but must not ship
-        // installed - it silently corrupts real save progression for every
-        // player, not just the one synthetic test scenario it was written for.
-        // InstallGetComponentNameSkipHook();
-        InstallStrlenNullGuardHook();
-        InstallInternStringDiagHook();
-        InstallFatalLogCallerTraceHook();
-        InstallResolveDisplayTextHook();
-        InstallResolveDisplayTextWrapperDiagHook();
-        InstallLayoutScreenCtorHook();
-        InstallModSlotSelectedHook();
-        InstallFireOutputDiagHook();
-        InstallPrefabLookupDiagHook();
-        // NOT installed (cont.43): live-tested and found to break touch
-        // responsiveness on car_select once installed, for reasons not yet
-        // understood (sub_16C660 itself runs fine every frame through the
-        // hook per its own diagnostics - "returned 0" every ~16ms, no hang
-        // - yet taps stop registering; reproduced 5/5 tries with the hook
-        // installed vs 1/1 without). sub_16C660 is called at a much higher,
-        // more global frequency (~60/sec, from app boot onward) than any
-        // other function hooked in this project - too risky to keep
-        // chasing blind. See lan_event_injection.h for the full writeup;
-        // the FireOutput-level interception was widened instead (does not
-        // need this hook).
-        // InstallConfirmCarSelectionHook();
-        InstallFlowNodeTickHook();
-    }
-
+    // Branch merge (2026-09-22): the native32/lan-event-injection-poc
+    // branch's own JNI_OnLoad installs ~20 hooks here (opponent
+    // substitution, cop/traffic removal, the LAN event-injection state
+    // machine, several crash workarounds) against a real dlopen'd
+    // libapp.so, available at JNI_OnLoad time. On this build libapp.so
+    // isn't loaded until Java calls loadEmulatedLibapp() well after
+    // JNI_OnLoad (see LoadEmulatedLibapp's own comment - no
+    // Context/AssetManager access this early) - `get_libapp_base()` would
+    // always be null here regardless, and every one of those Install*Hook
+    // calls resolves a raw "libapp_base + OFFSET" function pointer that
+    // needs GuestFn/CallGuestFunction plumbing to be callable at all (see
+    // this file's own comment above the commented-out includes). None of
+    // it is wired in here - deliberately, not an oversight - pending the
+    // same porting session as lan_event_injection.h/
+    // opponent_substitution.h/cop_traffic_disable.h themselves.
     return JNI_VERSION_1_6;
 }
 
+// Called from Kotlin once it has extracted the bundled armeabi-v7a
+// libapp.so asset to a real file (see GameActivityMain.kt) - loads it
+// through the embedded ARM32 emulation core and installs whichever hooks
+// are enabled. Returns true on success. See ARM64_TRANSLATION_LAYER.md and
+// this file's own comment above the (currently excluded)
+// "#include lan_event_injection.h" line for what is and isn't wired up yet.
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_nfs_mod_mpcore_MultiplayerCore_loadEmulatedLibapp(JNIEnv* env, jobject thiz, jstring path) {
+    const char* pathUtf8 = env->GetStringUTFChars(path, nullptr);
+    bool ok = LoadEmulatedLibapp(pathUtf8, env, thiz);
+    env->ReleaseStringUTFChars(path, pathUtf8);
+    if (!ok) return JNI_FALSE;
+
+    if (kEnableTrackSubstitutionHook) {
+        InstallBuildTrackScenePathHook();
+    }
+    if (kEnableMapScreenCtorTraceHook) {
+        InstallMapScreenCtorTraceHook();
+    }
+    Log("loadEmulatedLibapp: libapp.so loaded into the emulation core, host base=%p", libapp_base);
+    return JNI_TRUE;
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_nfs_mod_mpcore_MultiplayerCore_bumpBackTraceToLogcat(JNIEnv *env, jobject thiz) {
    //backtraceToLogcat();
 }
 
-// cont.44: lets Kotlin (eventually a real lobby-overlay button, for now a
-// debug broadcast receiver - see GameActivityMain.kt) open car_select on
-// demand instead of only automatically at boot. See
-// TriggerOpenCarSelectOnDemand in lan_event_injection.h for the details.
+// cont.44/48's on-demand car_select triggers depend on the LAN
+// event-injection subsystem, which isn't wired into this emulated build yet
+// (see the comment above this file's excluded lan_event_injection.h
+// include). Kept as no-op JNI stubs, not removed outright, so
+// MultiplayerCore.kt's existing `external fun` declarations still link.
 extern "C"
 JNIEXPORT void JNICALL
 Java_nfs_mod_mpcore_MultiplayerCore_triggerCarSelectTest(JNIEnv *env, jobject thiz) {
-    TriggerOpenCarSelectOnDemand();
+    Log("triggerCarSelectTest: not available yet in the ARM64 emulated-core build (see main.cpp)");
 }
 
-// cont.48: experimental TRUE direct jump to car_select, bypassing
-// EventDetails entirely - see TriggerTrueDirectCarSelectJump in
-// lan_event_injection.h for the details and the real risk involved.
 extern "C"
 JNIEXPORT void JNICALL
 Java_nfs_mod_mpcore_MultiplayerCore_triggerTrueDirectCarSelectJump(JNIEnv *env, jobject thiz) {
-    TriggerTrueDirectCarSelectJump();
+    Log("triggerTrueDirectCarSelectJump: not available yet in the ARM64 emulated-core build (see main.cpp)");
 }

mpcore/src/main/cpp/real_native_call.h

@@ -0,0 +1,24 @@
+#pragma once
+
+// Shared helper for the JNIEXPORT wrappers in game_lifecycle_stubs*.cpp:
+// calls one of libapp.so's own real native functions (real_native_offsets.h)
+// through the emulation core, marshaling `env`/`thiz` into the guest JNIEnv/
+// jobject handle scheme (emu/jni_shim.h) first.
+#include <jni.h>
+#include <vector>
+#include "emu/guest_engine.h"
+#include "emu/jni_shim.h"
+
+inline uint32_t CallRealNative(JNIEnv* env, jobject thiz, GuestAddr offset,
+                                std::initializer_list<uint32_t> extraArgs = {}) {
+    JniShim::Instance().SetRealEnv(env);
+    GuestAddr guestEnv = JniShim::Instance().BuildGuestJNIEnv(GuestEngine::Instance());
+    uint32_t guestThiz = JniShim::Instance().handles().Alloc(thiz);
+    std::vector<uint32_t> args = {guestEnv, guestThiz};
+    args.insert(args.end(), extraArgs);
+    return GuestEngine::Instance().CallGuestFunction(offset, args.data(), (int)args.size());
+}
+
+inline uint32_t GuestHandleFor(jobject obj) {
+    return JniShim::Instance().handles().Alloc(obj);
+}

mpcore/src/main/cpp/real_native_offsets.h

@@ -0,0 +1,51 @@
+#pragma once
+
+// Real guest addresses of libapp.so's own JNI-exported native functions -
+// found this session via a plain .dynsym dump (readelf/pyelftools), NOT IDA
+// RE: even though the file is stripped, JNI symbols stay in .dynsym so the
+// dynamic linker/dlsym can find them, which meant every one of these was
+// available for free. See ARM64_TRANSLATION_LAYER.md's "boot the game"
+// follow-up notes for context. All are ARM-mode entry points (standard for
+// this NDK/compiler combination, consistent with every other hooked offset
+// in this codebase already being ARM-mode).
+//
+// Verify with: readelf -sW native_lib/libapp.so | grep 'Java_\|JNI_OnLoad'
+
+#define REAL_JNI_ONLOAD_OFFSET 0x54e124
+
+#define REAL_EAIO_STARTUP_OFFSET 0x6bc7d4
+#define REAL_EAIO_SHUTDOWN_OFFSET 0x6bc804
+#define REAL_STORAGEDIR_STARTUP_OFFSET 0x764264
+#define REAL_STORAGEDIR_SHUTDOWN_OFFSET 0x764378
+#define REAL_EATHREAD_INIT_OFFSET 0x643328
+
+#define REAL_NIMBLE_ON_APP_LAUNCH_OFFSET 0x96c781
+#define REAL_NIMBLE_ON_APP_QUIT_OFFSET 0x96c8c9
+#define REAL_NIMBLE_ON_APP_RESUME_OFFSET 0x96c855
+#define REAL_NIMBLE_ON_APP_SUSPEND_OFFSET 0x96c7f5
+#define REAL_NIMBLE_ON_UPDATE_LAUNCH_METHOD_OFFSET 0x96c925
+
+#define REAL_GAMEACTIVITY_ONCREATE_OFFSET 0x54c6e0
+#define REAL_GAMEACTIVITY_ONDESTROY_OFFSET 0x54cb20
+#define REAL_GAMEACTIVITY_ONMUSICPLAYERSTATECHANGED_OFFSET 0x54cfc8
+#define REAL_GAMEACTIVITY_ONORIENTATIONCHANGE_OFFSET 0x54cfe4
+#define REAL_GAMEACTIVITY_ONPAUSE_OFFSET 0x54c904
+#define REAL_GAMEACTIVITY_ONPHYSICALKEYDOWN_OFFSET 0x54cb98
+#define REAL_GAMEACTIVITY_ONPHYSICALKEYUP_OFFSET 0x54cc88
+#define REAL_GAMEACTIVITY_ONPHYSICALNAVIGATIONVISIBILITYCHANGED_OFFSET 0x54cd84
+#define REAL_GAMEACTIVITY_ONRESTART_OFFSET 0x54c900
+#define REAL_GAMEACTIVITY_ONRESUME_OFFSET 0x54c920
+#define REAL_GAMEACTIVITY_ONSTART_OFFSET 0x54c8e4
+#define REAL_GAMEACTIVITY_ONSTOP_OFFSET 0x54c93c
+#define REAL_GAMEACTIVITY_RESTORECONTEXT_OFFSET 0x54cb70
+#define REAL_GAMEACTIVITY_SURFACECHANGED_OFFSET 0x54cb50
+#define REAL_GAMEACTIVITY_SURFACECREATED_OFFSET 0x54cb48
+
+#define REAL_RUNLOOP_TICK_OFFSET 0x54e100
+
+#define REAL_MOGA_ONKEYEVENT_OFFSET 0x265ea0
+#define REAL_MOGA_ONMOTIONEVENT_OFFSET 0x2667a0
+#define REAL_MOGA_ONSTATEEVENT_OFFSET 0x266cdc
+
+#define REAL_GLSURFACEVIEW_TOUCHPAD_OFFSET 0x54d9d4
+#define REAL_GLSURFACEVIEW_TOUCHSCREEN_OFFSET 0x54d764

mpcore/src/main/cpp/third_party/unicorn/.clang-format

@@ -0,0 +1,16 @@
+BasedOnStyle: LLVM
+IndentWidth: 4
+UseTab: Never
+BreakBeforeBraces: Linux
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortBlocksOnASingleLine: Empty
+AllowShortFunctionsOnASingleLine: Empty
+AllowShortLoopsOnASingleLine: false
+IndentCaseLabels: false
+ColumnLimit: 80
+SortIncludes: false
+AllowShortLambdasOnASingleLine: Inline
+AlwaysBreakBeforeMultilineStrings: false
+BreakStringLiterals: true
+PointerAlignment: Right

mpcore/src/main/cpp/third_party/unicorn/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs/Unicorn_Engine_Documentation"]
+	path = docs/Unicorn_Engine_Documentation
+	url = https://github.com/kabeor/Unicorn-Engine-Documentation

mpcore/src/main/cpp/third_party/unicorn/AUTHORS.TXT

@@ -0,0 +1,2 @@
+Nguyen Anh Quynh <aquynh -at- gmail.com>
+Dang Hoang Vu <dang.hvu -at- gmail.com>

mpcore/src/main/cpp/third_party/unicorn/COPYING

@@ -0,0 +1,339 @@
+		    GNU GENERAL PUBLIC LICENSE
+		       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+			    Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+		    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+			    NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+		     END OF TERMS AND CONDITIONS
+
+	    How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, write to the Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.

mpcore/src/main/cpp/third_party/unicorn/COPYING.LGPL2

@@ -0,0 +1,481 @@
+                  GNU LIBRARY GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1991 Free Software Foundation, Inc.
+ 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+[This is the first released version of the library GPL.  It is
+ numbered 2 because it goes with version 2 of the ordinary GPL.]
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.
+
+  This license, the Library General Public License, applies to some
+specially designated Free Software Foundation software, and to any
+other libraries whose authors decide to use it.  You can use it for
+your libraries, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if
+you distribute copies of the library, or if you modify it.
+
+  For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link a program with the library, you must provide
+complete object files to the recipients so that they can relink them
+with the library, after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+  Our method of protecting your rights has two steps: (1) copyright
+the library, and (2) offer you this license which gives you legal
+permission to copy, distribute and/or modify the library.
+
+  Also, for each distributor's protection, we want to make certain
+that everyone understands that there is no warranty for this free
+library.  If the library is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original
+version, so that any problems introduced by others will not reflect on
+the original authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that companies distributing free
+software will individually obtain patent licenses, thus in effect
+transforming the program into proprietary software.  To prevent this,
+we have made it clear that any patent must be licensed for everyone's
+free use or not licensed at all.
+
+  Most GNU software, including some libraries, is covered by the ordinary
+GNU General Public License, which was designed for utility programs.  This
+license, the GNU Library General Public License, applies to certain
+designated libraries.  This license is quite different from the ordinary
+one; be sure to read it in full, and don't assume that anything in it is
+the same as in the ordinary license.
+
+  The reason we have a separate public license for some libraries is that
+they blur the distinction we usually make between modifying or adding to a
+program and simply using it.  Linking a program with a library, without
+changing the library, is in some sense simply using the library, and is
+analogous to running a utility program or application program.  However, in
+a textual and legal sense, the linked executable is a combined work, a
+derivative of the original library, and the ordinary General Public License
+treats it as such.
+
+  Because of this blurred distinction, using the ordinary General
+Public License for libraries did not effectively promote software
+sharing, because most developers did not use the libraries.  We
+concluded that weaker conditions might promote sharing better.
+
+  However, unrestricted linking of non-free programs would deprive the
+users of those programs of all benefit from the free status of the
+libraries themselves.  This Library General Public License is intended to
+permit developers of non-free programs to use free libraries, while
+preserving your freedom as a user of such programs to change the free
+libraries that are incorporated in them.  (We have not seen how to achieve
+this as regards changes in header files, but we have achieved it as regards
+changes in the actual functions of the Library.)  The hope is that this
+will lead to faster development of free libraries.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library".  The
+former contains code derived from the library, while the latter only
+works together with the library.
+
+  Note that it is possible for a library to be covered by the ordinary
+General Public License rather than by this special one.
+
+                  GNU LIBRARY GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License Agreement applies to any software library which
+contains a notice placed by the copyright holder or other authorized
+party saying it may be distributed under the terms of this Library
+General Public License (also called "this License").  Each licensee is
+addressed as "you".
+
+  A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+  The "Library", below, refers to any such software library or work
+which has been distributed under these terms.  A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term "modification".)
+
+  "Source code" for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.
+
+  Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+  
+  1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+  You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+  2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) The modified work must itself be a software library.
+
+    b) You must cause the files modified to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    c) You must cause the whole of the work to be licensed at no
+    charge to all third parties under the terms of this License.
+
+    d) If a facility in the modified Library refers to a function or a
+    table of data to be supplied by an application program that uses
+    the facility, other than as an argument passed when the facility
+    is invoked, then you must make a good faith effort to ensure that,
+    in the event an application does not supply such function or
+    table, the facility still operates, and performs whatever part of
+    its purpose remains meaningful.
+
+    (For example, a function in a library to compute square roots has
+    a purpose that is entirely well-defined independent of the
+    application.  Therefore, Subsection 2d requires that any
+    application-supplied function or table used by this function must
+    be optional: if the application does not supply it, the square
+    root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library.  To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License.  (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.)  Do not make any other change in
+these notices.
+
+  Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+  This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+  4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+  If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library".  Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+  However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library".  The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+  When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+  If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+  Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+  6. As an exception to the Sections above, you may also compile or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+  You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+    a) Accompany the work with the complete corresponding
+    machine-readable source code for the Library including whatever
+    changes were used in the work (which must be distributed under
+    Sections 1 and 2 above); and, if the work is an executable linked
+    with the Library, with the complete machine-readable "work that
+    uses the Library", as object code and/or source code, so that the
+    user can modify the Library and then relink to produce a modified
+    executable containing the modified Library.  (It is understood
+    that the user who changes the contents of definitions files in the
+    Library will not necessarily be able to recompile the application
+    to use the modified definitions.)
+
+    b) Accompany the work with a written offer, valid for at
+    least three years, to give the same user the materials
+    specified in Subsection 6a, above, for a charge no more
+    than the cost of performing this distribution.
+
+    c) If distribution of the work is made by offering access to copy
+    from a designated place, offer equivalent access to copy the above
+    specified materials from the same place.
+
+    d) Verify that the user has already received a copy of these
+    materials or that you have already sent this user a copy.
+
+  For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the source code distributed need not include anything that is normally
+distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.
+
+  It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+  7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+    a) Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other library
+    facilities.  This must be distributed under the terms of the
+    Sections above.
+
+    b) Give prominent notice with the combined library of the fact
+    that part of it is a work based on the Library, and explaining
+    where to find the accompanying uncombined form of the same work.
+
+  8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License.  Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License.  However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+  9. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Library or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+  10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+  13. The Free Software Foundation may publish revised and/or new
+versions of the Library General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+  14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission.  For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+                            NO WARRANTY
+
+  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+           How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the library's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Library General Public
+    License as published by the Free Software Foundation; either
+    version 2 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Library General Public License for more details.
+
+    You should have received a copy of the GNU Library General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the library, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the
+  library `Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+  <signature of Ty Coon>, 1 April 1990
+  Ty Coon, President of Vice
+
+That's all there is to it!

mpcore/src/main/cpp/third_party/unicorn/COPYING_GLIB

@@ -0,0 +1,482 @@
+		  GNU LIBRARY GENERAL PUBLIC LICENSE
+		       Version 2, June 1991
+
+ Copyright (C) 1991 Free Software Foundation, Inc.
+    		    59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+[This is the first released version of the library GPL.  It is
+ numbered 2 because it goes with version 2 of the ordinary GPL.]
+
+			    Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.
+
+  This license, the Library General Public License, applies to some
+specially designated Free Software Foundation software, and to any
+other libraries whose authors decide to use it.  You can use it for
+your libraries, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if
+you distribute copies of the library, or if you modify it.
+
+  For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link a program with the library, you must provide
+complete object files to the recipients so that they can relink them
+with the library, after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+  Our method of protecting your rights has two steps: (1) copyright
+the library, and (2) offer you this license which gives you legal
+permission to copy, distribute and/or modify the library.
+
+  Also, for each distributor's protection, we want to make certain
+that everyone understands that there is no warranty for this free
+library.  If the library is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original
+version, so that any problems introduced by others will not reflect on
+the original authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that companies distributing free
+software will individually obtain patent licenses, thus in effect
+transforming the program into proprietary software.  To prevent this,
+we have made it clear that any patent must be licensed for everyone's
+free use or not licensed at all.
+
+  Most GNU software, including some libraries, is covered by the ordinary
+GNU General Public License, which was designed for utility programs.  This
+license, the GNU Library General Public License, applies to certain
+designated libraries.  This license is quite different from the ordinary
+one; be sure to read it in full, and don't assume that anything in it is
+the same as in the ordinary license.
+
+  The reason we have a separate public license for some libraries is that
+they blur the distinction we usually make between modifying or adding to a
+program and simply using it.  Linking a program with a library, without
+changing the library, is in some sense simply using the library, and is
+analogous to running a utility program or application program.  However, in
+a textual and legal sense, the linked executable is a combined work, a
+derivative of the original library, and the ordinary General Public License
+treats it as such.
+
+  Because of this blurred distinction, using the ordinary General
+Public License for libraries did not effectively promote software
+sharing, because most developers did not use the libraries.  We
+concluded that weaker conditions might promote sharing better.
+
+  However, unrestricted linking of non-free programs would deprive the
+users of those programs of all benefit from the free status of the
+libraries themselves.  This Library General Public License is intended to
+permit developers of non-free programs to use free libraries, while
+preserving your freedom as a user of such programs to change the free
+libraries that are incorporated in them.  (We have not seen how to achieve
+this as regards changes in header files, but we have achieved it as regards
+changes in the actual functions of the Library.)  The hope is that this
+will lead to faster development of free libraries.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library".  The
+former contains code derived from the library, while the latter only
+works together with the library.
+
+  Note that it is possible for a library to be covered by the ordinary
+General Public License rather than by this special one.
+
+		  GNU LIBRARY GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License Agreement applies to any software library which
+contains a notice placed by the copyright holder or other authorized
+party saying it may be distributed under the terms of this Library
+General Public License (also called "this License").  Each licensee is
+addressed as "you".
+
+  A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+  The "Library", below, refers to any such software library or work
+which has been distributed under these terms.  A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term "modification".)
+
+  "Source code" for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.
+
+  Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+  
+  1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+  You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+  2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) The modified work must itself be a software library.
+
+    b) You must cause the files modified to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    c) You must cause the whole of the work to be licensed at no
+    charge to all third parties under the terms of this License.
+
+    d) If a facility in the modified Library refers to a function or a
+    table of data to be supplied by an application program that uses
+    the facility, other than as an argument passed when the facility
+    is invoked, then you must make a good faith effort to ensure that,
+    in the event an application does not supply such function or
+    table, the facility still operates, and performs whatever part of
+    its purpose remains meaningful.
+
+    (For example, a function in a library to compute square roots has
+    a purpose that is entirely well-defined independent of the
+    application.  Therefore, Subsection 2d requires that any
+    application-supplied function or table used by this function must
+    be optional: if the application does not supply it, the square
+    root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library.  To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License.  (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.)  Do not make any other change in
+these notices.
+
+  Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+  This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+  4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+  If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library".  Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+  However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library".  The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+  When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+  If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+  Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+  6. As an exception to the Sections above, you may also compile or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+  You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+    a) Accompany the work with the complete corresponding
+    machine-readable source code for the Library including whatever
+    changes were used in the work (which must be distributed under
+    Sections 1 and 2 above); and, if the work is an executable linked
+    with the Library, with the complete machine-readable "work that
+    uses the Library", as object code and/or source code, so that the
+    user can modify the Library and then relink to produce a modified
+    executable containing the modified Library.  (It is understood
+    that the user who changes the contents of definitions files in the
+    Library will not necessarily be able to recompile the application
+    to use the modified definitions.)
+
+    b) Accompany the work with a written offer, valid for at
+    least three years, to give the same user the materials
+    specified in Subsection 6a, above, for a charge no more
+    than the cost of performing this distribution.
+
+    c) If distribution of the work is made by offering access to copy
+    from a designated place, offer equivalent access to copy the above
+    specified materials from the same place.
+
+    d) Verify that the user has already received a copy of these
+    materials or that you have already sent this user a copy.
+
+  For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the source code distributed need not include anything that is normally
+distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.
+
+  It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+  7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+    a) Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other library
+    facilities.  This must be distributed under the terms of the
+    Sections above.
+
+    b) Give prominent notice with the combined library of the fact
+    that part of it is a work based on the Library, and explaining
+    where to find the accompanying uncombined form of the same work.
+
+  8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License.  Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License.  However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+  9. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Library or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+  10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+  13. The Free Software Foundation may publish revised and/or new
+versions of the Library General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+  14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission.  For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+			    NO WARRANTY
+
+  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+		     END OF TERMS AND CONDITIONS
+
+           How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the library's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Library General Public
+    License as published by the Free Software Foundation; either
+    version 2 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Library General Public License for more details.
+
+    You should have received a copy of the GNU Library General Public
+    License along with this library; if not, write to the 
+    Free Software Foundation, Inc., 59 Temple Place - Suite 330, 
+    Boston, MA  02111-1307  USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the library, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the
+  library `Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+  <signature of Ty Coon>, 1 April 1990
+  Ty Coon, President of Vice
+
+That's all there is to it!

mpcore/src/main/cpp/third_party/unicorn/CREDITS.TXT

@@ -0,0 +1,83 @@
+This file credits all the contributors of the Unicorn engine project.
+
+
+Key developers
+==============
+Nguyen Anh Quynh <aquynh -at- gmail.com>
+Dang Hoang Vu <dang.hvu -at- gmail.com>
+Huitao Chen (chenhuitao)
+Ziqiao Kong (lazymio)
+KaiJernLau (xwings)
+
+
+Beta testers (in no particular order)
+==============================
+Nguyen Tan Cong
+Loi Anh Tuan
+Edgar Barbosa
+Joxean Koret
+Chris Eagle
+Jay Little, Trail of Bits
+Jeong Wook Oh
+Luis Miras
+Yan Shoshitaishvili, Shellphish & UC Santa Barbara
+Erik Fischer
+Darel Griffin, NCC Group
+Anton Cherepanov
+Mohamed Saher (halsten)
+Tyler Colgan
+Jonathon Reinhart
+Blue Skeye
+Chris Maixner
+Sergi Alvarez, aka pancake (author of radare)
+Ryan Hileman
+Tim "diff" Strazzere
+WanderingGlitch of the Zero Day Initiative
+Sascha Schirra
+François Serman
+Sean Heelan
+Luke Burnett
+Parker Thompson
+Daniel Godas-Lopez
+Antonio "s4tan" Parata
+Corey Kallenberg
+Shift
+Gabriel Quadros
+Fabian Yamaguchi
+Ralf-Philipp Weinmann
+Mike Guidry
+Joshua "posixninja" Hill
+
+
+Contributors (in no particular order)
+=====================================
+(Please let us know if you want to have your name here)
+
+Nguyen Tan Cong
+Loi Anh Tuan
+Shaun Wheelhouse: Homebrew package
+Kamil Rytarowski: Pkgsrc package
+Zak Escano: MSVC support.
+Chris Eagle: Java binding
+Ryan Hileman: Go binding
+Antonio Parata: .NET binding
+Jonathon Reinhart: C unit test
+Sascha Schirra: Ruby binding
+Adrian Herrera: Haskell binding
+practicalswift: Various cool bugs found by fuzzing
+farmdve: Memory leaking fix
+Andrew Dutcher: uc_context_{save, restore} API.
+Stephen Groat: improved CI setup.
+David Zimmer: VB6 binding.
+zhangwm: ARM & ARM64 big endian.
+Mohamed Osama: FreePascal/Delphi binding.
+Philippe Antoine (Catena cyber): fuzzing 
+Huitao Chen (chenhuitao) & KaiJern Lau (xwings): Cmake support
+Huitao Chen (chenhuitao) & KaiJern Lau (xwings): Python3 support for building
+Kevin Foo (chfl4gs): Travis-CI migration
+Simon Gorchakov: PowerPC target
+Stuart Dootson (studoot): MSVC compatibility with PowerPC target support
+Ziqiao Kong (lazymio): uc_context_free() API and various bug fix & improvement.
+Sven Almgren (blindmatrix): bug fix
+Chenxu Wu (kabeor): Documentation
+Philipp Takacs: virtual tlb, memory snapshots

mpcore/src/main/cpp/third_party/unicorn/Cargo.toml

@@ -0,0 +1,105 @@
+[workspace]
+members = ["bindings/rust/unicorn-engine"]
+resolver = "2"
+
+[workspace.package]
+rust-version = "1.85.0"
+version = "2.1.5"
+authors = ["Ziqiao Kong <mio@lazym.io>", "Lukas Seidel", "Amaan Qureshi <amaanq12@gmail.com>"]
+keywords = ["unicorn", "cpu", "emulator", "bindings"]
+categories = ["api-bindings", "emulators", "no-std", "virtualization"]
+documentation = "https://github.com/unicorn-engine/unicorn/wiki"
+edition = "2024"
+license = "GPL-2.0"
+readme = "./bindings/rust/sys/README.md"
+repository = "https://github.com/unicorn-engine/unicorn"
+description = "Rust bindings for the Unicorn emulator with utility functions"
+
+[workspace.lints.clippy]
+cast_lossless = "allow"
+cast_possible_truncation = "allow"
+cast_possible_wrap = "allow"
+cast_sign_loss = "allow"
+missing_errors_doc = "allow"
+missing_panics_doc = "allow"
+similar_names = "allow"
+unreadable_literal = "allow"
+use_self = "allow"
+pedantic = { level = "warn", priority = -1 }
+nursery = { level = "warn", priority = -1 }
+cargo = { level = "warn", priority = -1 }
+
+# Root package
+[package]
+name = "unicorn-engine-sys"
+version.workspace = true
+authors.workspace = true
+keywords.workspace = true
+categories = [
+	"api-bindings",
+	"emulators",
+	"external-ffi-bindings",
+	"no-std",
+	"virtualization",
+]
+documentation.workspace = true
+edition.workspace = true
+license.workspace = true
+readme = "README.md"
+repository.workspace = true
+description.workspace = true
+links = "unicorn"
+# Cargo package --list
+exclude = [
+    "/docs",
+    "/bindings/dotnet",
+    "/bindings/go",
+    "/bindings/haskell",
+    "/bindings/java",
+    "/bindings/pascal",
+    "/bindings/python",
+    "/bindings/ruby",
+    "/bindings/vb6",
+    "/bindings/zig",
+    "/samples",
+    "/tests",
+]
+
+[lib]
+path = "bindings/rust/sys/src/lib.rs"
+
+[lints]
+workspace = true
+
+[build-dependencies]
+bindgen = "0.71.1"
+cc = { version = "1.2.17" }
+cmake = { version = "0.1.54" }
+heck = "0.5.0"
+pkg-config = { version = "0.3.32" }
+
+[features]
+default = ["arch_all"]
+dynamic_linkage = []
+arch_all = [
+	"arch_x86",
+	"arch_arm",
+	"arch_aarch64",
+	"arch_riscv",
+	"arch_mips",
+	"arch_sparc",
+	"arch_m68k",
+	"arch_ppc",
+	"arch_s390x",
+	"arch_tricore",
+]
+arch_x86 = []
+arch_arm = []
+arch_aarch64 = ["arch_arm"]
+arch_riscv = []
+arch_mips = []
+arch_sparc = []
+arch_m68k = []
+arch_ppc = []
+arch_s390x = []
+arch_tricore = []

mpcore/src/main/cpp/third_party/unicorn/ChangeLog

@@ -0,0 +1,550 @@
+This file details the changelog of Unicorn Engine.
+
+-------------------------------
+[Version 2.1.4]: September 9th, 2025
+
+Hello everyone. It has been a while since last release and we are releasing Unicorn 2.1.4. Though it is a patch release, there are some highlights worth mentioning.
+
+The very first thing is that, Unicorn (finally!) offers consistent PC guarantee in all cases. Well, it might sound weird that why it was not. Generally QEMU is not designed to keep PC synced in all cases for performance and Unicorn once put necessary hacks but those hacks were too hard to maintain. Now we have architecture agnostic mechanism to offer the PC guarantee.
+
+In addition, we offer a standalone unicorn Rust crate `unicorn-engine-sys` to allows users to build their own bindings since v2.1.4. There are also lots of bindings improvements contained in this release.
+
+We also fix the building and distribution issues for macos ARM and distribute wheels again. Our friend @patryk4815 from pwndbg helps sort this out. Kudos to him!
+
+For 2.2.0, personally I wish I could work it out before the end of this year, by merging lots of pending big PRs but my time budget is relatively limited recently. Please aware that 2.2.0 would probably bump QEMU version to 5.1.0 or even higher so semantics could be changed. Any help is highly welcome and please contact @wtdcode if you are keen.
+
+Lastly, I would like to express my deep gratitude to all contributors that help make this release happen, specifically @Evian-Zhang for Rust improvements and unicornafl integration, @Antelox for consistent contributions on our workflows, @amaanq for various huge work, reviews and Rust bindings split, @PhilippTakacs for PR reviews and fix. Again, thanks for every contributor!
+
+Below goes the auto generated release notes. Starting from this tag, the release note will switch to a short passage plus Github generated contents because this makes it easier to follow big changes.
+
+## What's Changed
+* bindings/zig: Fix sample_riscv_zig partial writes and logging by @fervagar in https://github.com/unicorn-engine/unicorn/pull/2133
+* Fix physical address truncation on 32-bit systems with addressing extensions by @ExhoAR22 in https://github.com/unicorn-engine/unicorn/pull/2139
+* refactor(lib): mark pointers as const where possible by @amaanq in https://github.com/unicorn-engine/unicorn/pull/2140
+* bindings: ruby: fix unexpected uc_query result pointer type by @anthraxx in https://github.com/unicorn-engine/unicorn/pull/1962
+* bindings: ruby: fix version identifier to 2.1.3 by @anthraxx in https://github.com/unicorn-engine/unicorn/pull/2142
+* feat(arm): add an `ESR` register by @amaanq in https://github.com/unicorn-engine/unicorn/pull/2155
+* fix(rust): watch all source and header files by @amaanq in https://github.com/unicorn-engine/unicorn/pull/2159
+* feat(rust): improve ARM CP register ergonomics by @amaanq in https://github.com/unicorn-engine/unicorn/pull/2160
+* fix(m68k): correct SR register read by @amaanq in https://github.com/unicorn-engine/unicorn/pull/2161
+* fix(python): catch `BaseException` in wrappers instead of `Exception` by @amaanq in https://github.com/unicorn-engine/unicorn/pull/2163
+* Remove the size limit for memory read and write (revamped) by @rliebig in https://github.com/unicorn-engine/unicorn/pull/2144
+* Loongarch port by @wtdcode in https://github.com/unicorn-engine/unicorn/pull/2164
+* S390x registers by @wtdcode in https://github.com/unicorn-engine/unicorn/pull/2167
+* Add from_handle_with_data method by @Evian-Zhang in https://github.com/unicorn-engine/unicorn/pull/2169
+* Make Unicorn struct clone-able by @Evian-Zhang in https://github.com/unicorn-engine/unicorn/pull/2170
+* Add Display and Error impl for uc_error for Rust bindings by @Evian-Zhang in https://github.com/unicorn-engine/unicorn/pull/2171
+* Add edge generated callback by @Evian-Zhang in https://github.com/unicorn-engine/unicorn/pull/2176
+* Correctly restore skip_sync_pc_on_exit by @Evian-Zhang in https://github.com/unicorn-engine/unicorn/pull/2181
+* Added CFG check and standalone flag for .NET binding by @AdvDebug in https://github.com/unicorn-engine/unicorn/pull/2182
+* qemu/configure: make strings command can be redefined by ${STRINGS} by @clan in https://github.com/unicorn-engine/unicorn/pull/2186
+* fix x86 pc by @wtdcode in https://github.com/unicorn-engine/unicorn/pull/2187
+* Patch from Saferewrite by @wtdcode in https://github.com/unicorn-engine/unicorn/pull/2188
+* fix incorrect ret of trampoline `closure` in `alloc_code_gen_buffer` by @HyperSine in https://github.com/unicorn-engine/unicorn/pull/2197
+* reset invalid_error before ram_block_add by @PhilippTakacs in https://github.com/unicorn-engine/unicorn/pull/2189
+* add uc_mem_read_virtual by @PhilippTakacs in https://github.com/unicorn-engine/unicorn/pull/2121
+* Minor fixes for vmem apis by @wtdcode in https://github.com/unicorn-engine/unicorn/pull/2199
+* glib_compat/glib_compact: Clear the buffer in g_hash_table_resize by @MarsDoge in https://github.com/unicorn-engine/unicorn/pull/2219
+* Enable install for rust bindings by @wtdcode in https://github.com/unicorn-engine/unicorn/pull/2224
+* Remove ninja installation from macos runners by @scribam in https://github.com/unicorn-engine/unicorn/pull/2225
+* Fix `read_sprr_perm` for Apple real CPUs and GitHub Actions; enable Apple ARM64 wheel builds on PyPI. Fixes #2033. by @patryk4815 in https://github.com/unicorn-engine/unicorn/pull/2227
+* Bump cmake minimum required version to 3.10 by @scribam in https://github.com/unicorn-engine/unicorn/pull/2226
+* Add support for clangarm64 by @scribam in https://github.com/unicorn-engine/unicorn/pull/2228
+* Revert "glib_compat/glib_compact: Clear the buffer in g_hash_table_resize" by @wtdcode in https://github.com/unicorn-engine/unicorn/pull/2220
+* Python bindings: Use ABI3 wheels by @Antelox in https://github.com/unicorn-engine/unicorn/pull/2223
+* concurrent control by @wtdcode in https://github.com/unicorn-engine/unicorn/pull/2235
+
+## New Contributors
+* @fervagar made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2133
+* @ExhoAR22 made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2139
+* @anthraxx made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1962
+* @rliebig made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2144
+* @AdvDebug made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2182
+* @HyperSine made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2197
+* @MarsDoge made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2219
+* @patryk4815 made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2227
+
+**Full Changelog**: https://github.com/unicorn-engine/unicorn/compare/v2.1.3...v2.1.4
+
+-------------------------------
+[Version 2.1.3]: March 7th, 2025
+
+2.1.3 includes a few fixes for distribution and stability issues. We urge users to update their versions as previous version contains security vulnerabilities.
+
+Fix & Improvements
+
+- Several security issues fixes. @PhilippTakacs 
+- Add alpine workflow and fix several distribution issues. @Antelox 
+- Introduce importlib_resources for py3.8 (EOL already) @Arusekk @Antelox 
+- Mips64 improvemtns. @OBarronCS 
+- mips related fixes and implement a few registers.
+- x86 default cpu model is changed to `UC_CPU_X86_HASWELL` and remove a few quirks.
+- Fix CR4 implementation.
+- Fix python bindings break changes by adding back `ctl_tlb_mode`. @Antelox 
+
+New Contributors
+* @OBarronCS made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2111
+
+Full Changelog: https://github.com/unicorn-engine/unicorn/compare/2.1.2...2.1.3
+
+-------------------------------
+[Version 2.1.2]: Feb 13rd, 2025
+2.1.2 is a patch release to mainly resolve the stability issue of the 2.1.0 release series and fix a few distribution issues. All users of Unicorn are expected to upgrade. 
+
+Highlights
+
+- macOS arm64 no longer provides binary wheels due to a feature missing from Github Action runners.
+- py3.8 support is brought back, python2 wheels are built and test as well and we migrate to cibuildwheel! @Antelox 
+- Several polish to python bindings and implement new API. @elicn  @droe 
+- Revert previous break changes that return UC_ERR_ARG for non-existing registers. Now this prints a warning. We urge all users relying on this behavior to fix code as soon as possible.
+- Fix several segment faults, including a few long-standing random segfault issues.
+- Revive previous unicorn 1 test suite and related refactoring. @elicn @Antelox 
+- Optimize memory handling and notdirty writes for faster memory access and snapshots, especially useful for fuzzing. @PhilippTakacs 
+- RISC-V API updates. @apparentlymart 
+- fix UC_HOOK_MEM_READ on aarch64. @glennsec 
+- Support UC_TCG_OP_FLAG_CMP for ARM @dotCirill 
+- An alternative tag prefixed with "v" is added for golang compatibility.
+
+Fix & Improvements
+
+- Implement UC_ARM64_REG_WSP
+- Several fixes on arm64 macos @tbodt 
+- reg_read_batch and reg_write_batch @hsa1as 
+- Fix pc sync issue for SPARC, MIPS, x86. This also fixes PC sync issue within UC_HOOK_BLOCK hooks.
+- Allow cmake to install files on Windows and allow cmake not to generate Unicorn 1 style all-in-one objects archive 
+- Make i386 instructions RDTSC and RDTSCP hookable @t0rr3sp3dr0 
+- Allow Statically Linking in Go @t0rr3sp3dr0 
+- Rust bindings improvements @Sanae6 
+- Patch multiple UC_HOOK_MEM callbacks for unaligned access @Michael-c0de 
+- Fix UC_MEM_FETCH_PROT for data read
+- Remove more Unicorn 1 hacks to improve performance.
+- Docs & unit test updates. @saicao 
+- Allow uc_ctl_set_page_size() for arm64 @droe 
+- Musl builds @clan 
+- mips16 fix @ZakDanger 
+- Fix UC_HOOK_MEM on arm32 @xndcn 
+- Fix heap buffer overflow in op_cksm function @Shivam7-1 
+
+
+New Contributors
+* @droe made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2023
+* @Antelox made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2026
+* @tbodt made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2049
+* @hsa1as made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2060
+* @t0rr3sp3dr0 made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2066
+* @Sanae6 made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2069
+* @Michael-c0de made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2063
+* @Evian-Zhang made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2064
+* @glennsec made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2028
+* @clan made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2085
+* @xndcn made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2091
+* @Shivam7-1 made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2096
+* @amaanq made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2099
+
+Full Changelog: https://github.com/unicorn-engine/unicorn/compare/2.1.1...2.1.2
+
+As usual, thanks to all contributors and sorry if I missed your name here (please tell me @wtdcode !).
+
+Lastly and personally, I would like to express my big thanks to @Antelox @elicn and @PhilippTakacs for spending lots of time improving Unicorn Engine. Also, there are a few big pull requests adding new architectures (RH850, TCI,  LoongArch64, AVR) and I will actively push them to 2.2.0.
+
+-------------------------------
+[Version 2.1.1]: Sept 26th, 2024
+
+This is a small release to fix a few urgent issues.
+
+- Remove pkg_resources usage
+- Fix wheels distribution for x86_64 macos
+- Fix redundant wheel hacks
+- Support musllinux distribution
+
+-------------------------------
+[Version 2.1.0]: Sept 22nd, 2024
+
+It has been a while since the last release, and 2.1.0 brings several exciting features. Below is the changelog from the latest to the oldest (though not strictly).
+
+Highlights
+
+- Revive QEMU logs, now we have `-DUNICORN_LOGGING=yes` to enable all qemu logs. @BitMaskMixer 
+- Faster (up to 40x) write performance by not always doing `store_helper` and cleaning page locks. @tunz @boborjan2
+- Brand new python bindings, with strongly typed and many improvements. @elicn 
+- Fix to a long-standing MinGW random segfault bug.
+- We bring python2 compatibility back.
+- We now fully support M1, both building and a pre-built wheel.
+- We support snapshot memory now, with a very low overhead copy-on-write fashion. @PhilippTakacs 
+- An option to bypass MMU is also added, check our FAQ. @PhilippTakacs 
+- A brand new (and modern) java bindings. We are also working to publish it to maven. @nneonneo
+- We have zig integrated. @kassane @atipls 
+- Now Unicorn no longer allocates 2GB memory for every instance. The memory will be only committed once used and the upper limit can be adjusted with `uc_ctl`.
+- New DotNet binding, with published to both Github and Nuget. @TSRBerry 
+- The release will attach all binaries, thanks to @marameref 
+
+Fixes & Improvements
+
+- RISCV improvements, but we still have a long way to go. @apparentlymart @ks0777 
+- cmake improvements @scribam @es3n1n 
+- Various python bindings fix and improvements @bet4it @rhelmot 
+- Docs. @gerph @BitMaskMixer 
+- Rust bindings. @lockbox @mlgiraud @deadash
+- TCG backend fixes. @redoste @StalkR @dglynos 
+- PPC32 fixes. @dotCirill 
+- Haiku fixes. @kallisti5 
+- Improvements to avoid simulator detection. @mrexodia 
+
+New Contributors
+
+* @ks0777 made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1736
+* @LG3696 made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1764
+* @PhilippTakacs made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1765
+* @edsky made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1754
+* @tunz made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1790
+* @kassane made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1809
+* @Xeonacid made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1807
+* @nneonneo made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1830
+* @lockbox made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1847
+* @mlgiraud made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1849
+* @basavesh made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1861
+* @hamarituc made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1886
+* @StalkR made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1907
+* @dotCirill made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1910
+* @marameref made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1897
+* @redoste made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1922
+* @xclusivor made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1929
+* @elicn made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1629
+* @nganhkhoa made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1942
+* @es3n1n made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1960
+* @BitMaskMixer made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1977
+* @apparentlymart made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1995
+* @atipls made their first contribution in https://github.com/unicorn-engine/unicorn/pull/1985
+* @omer54463 made their first contribution in https://github.com/unicorn-engine/unicorn/pull/2005
+
+Full Changelog: https://github.com/unicorn-engine/unicorn/compare/2.0.1...2.1.0
+
+
+Again, thanks for all contributors and sorry if I missed your name here (please tell me @wtdcode !). 2.1.1 is also coming because we expect some minor break changes to fix.
+
+-------------------------------
+[Version 2.0.1.post1]: Nov 22nd, 2022
+
+This is a small release to complement the previous 2.0.1 release.
+
+Fix:
+
+- Fix the endianness detection in tests.
+- Fix the version number in CMakeLists.txt.
+
+-------------------------------
+[Version 2.0.1]: Nov 1st, 2022
+
+Unicorn2 makes the first step to [Debian packages](https://tracker.debian.org/pkg/unicorn-engine) and [vcpkg](https://github.com/microsoft/vcpkg/pull/26101)! Thanks @roehling and @LilyWangL !
+
+Features:
+
+- Support building & running on BE hosts. #1710 
+- Fix and support `clang-cl` on Windows. #1687 
+- Fix python `sdist` and add aarch64 Linux wheels. Note `pip` can build Unicorn2 on M1 now!
+- C# binding is refined and upgraded to .Net 6. #1723 
+
+Fix/Improvements:
+
+- Various bindings improvements. #1723
+- Improvements for tests. #1684 #1683 #1691 #1711 
+- Fail explicitly when VEX.L is set. #1658 
+- Fix endianness when writing PPC32 CR register. #1659 
+- Fix a bug in `uc_ctl_set_cpu_model` check.
+- Fix Tricore PC not updating. #1668 
+- Fix the mapping not updated if users modify the mappings in the hooks.
+- Handle pathological cases consistently. #1651 
+- Fix memory leaks in PPC target. #1680 
+- Fix memory leaks in Tricore target. #1681
+- Fix MSVC handling in cmake. #1693  
+- Fix PC sync-ing problems for `UC_HOOK_BLOCK` hooks.
+- Fix PC sync-ed twice when users request a soft restart.
+- Prevent overflow with pre-allocated RAM blocks. #1712 
+- Add FPCR and FPSR registers #1722 
+- Fix ARM CPU state not deep copied.
+- Fix PC not sync-ed for memory operation on aarch64.
+- Exit invalid store operations early to avoid the target registers being overwritten.
+- Improve the support for ARM BE32.
+
+Thanks:
+
+@roehling @LilyWangL @mrexodia @zachriggle @Yu3H0 @rhelmot @relapids @sh4w1 @TSRBerry
+
+-------------------------------
+[Version 2.0.0]: July 7th, 2022
+
+Features:
+
+- TriCore Support (#1568)
+
+Fixes/Improvements:
+
+- Build both shared library and static archive as unicorn1 does.
+- Misc bindings improvements. #1569 #1600 #1609  #1613 #1616
+- Make sure setjmp-setjmp-wrapper-win32 participates in the build. #1604 
+- Improve Rust bindings build logic.
+- Fix wrong python binding for UC_CTL_TB_REMOVE_CACHE
+- Flush translation blocks when the count hook is removed.
+- Fix unicorn crash when nested `uc_emu_start` deletes a hook
+- Fix CPU not fully resumed when writing PC.
+- Don't quit TB if `uc_mem_protect` doesn't change the protection of current TB memory.
+- Add type annotations for python bindings.
+- Add CPUID hook for python bindings. #1618 
+- Don't repeat memory hooks if there is already an unhandled error. #1618 
+- Support reads and writes over all Arm SIMD registers #1621
+- Fix wrong registers range in python bindings.
+- Fix uc_mem_protect on mmio regions
+- Fix a UAF caused by hook cache.
+- Fix the value collision between UC_MODE_ARMBE8 and UC_MODE_ARM926
+
+Thanks:
+
+@AfoHT @mrexodia @bet4it @lowlyw @ekilmer @ondryaso @QDucasse @PalumboN @uberwoozle
+
+----------------------------------
+[Version 2.0.0 rc7]: April 17, 2022
+
+This release is expected to be the real last RC release of Unicorn2. ;)
+
+Features:
+
+- Correctly generate static archives for the static build and have CI auto-tested.
+- Rust bindings revised. #1584 
+- Compatible with clang-cl compiler. #1581 
+- Implement UC_HOOK_INSN for aarch64 MRS/MSR/SYS/SYSL
+
+Fixes/Improvements:
+
+- Several corner cases on our API. #1587 #1595 
+- Fix the codegen buffer leak. 
+- Rust bindins improvements. #1574 #1575 
+- Add "holes" to allow unicorn lib as a drop-in replacement for older ones. #1572 
+- s390x backports. #1570 
+- Fix exits wrongly removed in nested uc_emu_start
+- Fix a possible endless loop for only one translation block in a multithreaded environment.
+- Fix wrong PC without `UC_HOOK_CODE` installed.
+- Update vb6 bindings license. #1563 
+- Fix buffer allocation failure on M1. #1559 
+- Fix wrong EFLAGS on startup.
+- Fix wrong internal states on nested uc_emu_start.
+- Remove armeb-softmmu and aarcheb-softmmu which are usermode targets.
+- Advance PPC32 PC. #1558 
+- Support UC_PPC_REG_CR.
+- Update CI to windows-2019
+
+Thanks:
+
+@shuffle2 @liyansong2018 @rose4096 @nviennot @n1tram1 @iii-i @dzzie @yrashk @bet4it 
+
+----------------------------------
+[Version 2.0.0 rc6]: Feburary 13, 2022
+
+This release is expected to be the last RC release of Unicorn2.
+
+Features:
+
+- SystemZ (aka. s390x) support.  #1521   #1547 
+- CPUID hook now may return a bool to indicate whether skipping the CPUID instruction.
+- ARM/AARCH64 coprocessor registers read/write support. #889 
+
+Fixes/Improvements:
+
+- Rust improvements. More registers enums #1504 Easier to use #1543 #1545 
+- M68k improvements. #1507 
+- Golang improvements. Enable `uc_ctl_set_model` #1506 
+- Unit tests improvements. #1512 
+- Various ARM system mode fixes. #1500 #1520 #1525  #1531 
+- Read/write arm FPSCR and FPSID. #1453 
+- Fix the support for ARMv8
+- Fix a large number of memory leaks and unicorn2 now goes with google/oss-fuzz!
+- Add more X87 registers.  #1524 
+- Add more PPC registers.
+- Fix the exception not cleared in python bindings. #1537 
+- Correctly support ARM big endian and drops `armeb-softmmu` and `aarch64eb-softmmu`
+- Fix ARM CPSR.E not reflected during runtime.
+- Resolve fuzzing speed problem on macOS.
+- Modernize CmakeFileLists.txt. #1544 
+- Fix an issue in nested `uc_emu_start`
+
+Thanks:
+
+@Kritzefitz @zznop @QDucasse @gerph @bet4it @mrexodia @iii-i @jbcayrou @scribam
+
+----------------------------------
+[Version 2.0.0 rc5]: November 25, 2021
+
+This release fixes a few urgent bugs and improves performance.
+
+Fixes/Improvements:
+
+- Rust bindings improvements. #1480 #1483
+- Allow R/W to cp15 registers. #1481 
+- Fix `UC_HOOK_EDGE_GENERATED` not calling for indirect jumps.
+- Python bindings build improvements. #1486
+- Fix bindings on m1 macOS.
+- Support nested `uc_emu_start` calls without context save/restore
+- Fix wrong MMIO offset for 32bit targets.
+- Fix wrong `uc_mem_unmap` logic for both ram and mmio memory.
+- Inline `uc_trace_code` and PC sync to improve performance.
+- Various fixes in tests.
+- Allow writing to CPSR to switch bank registers.
+- Implement MMIO in rust bindings. #1499 
+
+Thanks:
+
+- @domenukk 
+- @bet4it 
+- @mid-kid
+- @Kritzefitz
+
+----------------------------------
+[Version 2.0.0 rc4]: November 09, 2021
+
+This is a big release of Unicorn and introduces a few powerful new features and a bunch of fixes. 
+
+New Features:
+
+- New API: uc_ctl, by which you could control CPU models, TB caches or multiple exits etc.
+- New Hook: UC_HOOK_EDGE_GENERATED, UC_HOOK_TCG_OPCODE
+- RISCV CSR read/write.
+- Support reading MIPS hi/lo regs. 7268c2a19bce2db72b90e3ea3b133482c3ff4e58
+- OSS Fuzzing building support.
+- MSVC 32bit and Android build support.
+- Introduce clang-format.
+
+Fixes/Improvements:
+
+- Java bindings improvements. unicorn-engine/unicorn#1461
+- API Documents updates. unicorn-engine/unicorn#1459
+- Rust bindings improvements. unicorn-engine/unicorn#1462
+- Add a go.mod for go bindings.
+- CMakeLists.txt improvements as a subproject. #1373
+- Fix rust bindings build script and add CI.
+- Use binary search to find mappings. unicorn-engine/unicorn#1414
+- RISCV:
+  - Update pc when exiting execution. unicorn-engine/unicorn#1465
+  - Add RISCV control status registers to enable floating. unicorn-engine/unicorn#1469 unicorn-engine/unicorn#1478
+  - After `ecall`, pc not advanced. unicorn-engine/unicorn#1477
+- Fix tb not invalidated when exiting.
+- Fix bindings makefile.
+- Fix uc_mem_protect not working. unicorn-engine/unicorn#1468
+
+Thanks:
+
+- @bet4it
+- @kabeor
+- @chfl4gs 
+- @QDucasse
+- @h33p
+- @geohot
+- @cla7aye15I4nd
+- @jcalabres
+
+----------------------------------
+[Version 2.0.0 rc3]: October 06, 2021
+
+This is an urgent pre-release regarding python bindings on older Linux systems.
+
+- Support older Linux distribution, e.g. prior to Ubuntu 19.04
+- Fix a memory leak in `uc_close`
+- Support building on Android
+- Support hooking CPUID instruction.
+
+Enjoy.
+
+----------------------------------
+[Version 2.0.0 rc2]: October 05, 2021
+
+This is an urgent pre-release regarding the packaging problem of python bindings.
+
+- Set `zip_false` and `is_pure` to `False` to avoid issues on some Linux distributions.
+- Link to `libm` to make sure our libraries work.
+- Support to read ST registers in rust bindings.
+- Fix #1450
+
+Enjoy.
+
+----------------------------------
+[Version 2.0.0 rc1]: October 04, 2021
+
+Unicorn2 first release candidate!
+
+- Based on Qemu 5.0.1
+- Remain backward compatible with Unicorn 1.x
+- Update ISA of all existing architectures
+- Support 2 new architectures in PowerPC & RISCV
+
+----------------------------------
+[Unicorn2-beta]: October 3rd, 2021
+
+- Release Unicorn2 beta to public.
+- New logo to celebrate this important milestone!
+
+----------------------------------
+[Version 1.0.1]: April 20th, 2017
+
+- Properly handle selected-architecture build.
+- Fix compilation issues on PPC & S390x.
+- Fix a memory leak on uc_mem_protect().
+- ARM:
+    - Support big-endian mode.
+    - Correct instruction size of Thumb/Thumb2 code.
+    - Support read/write APSR register.
+- ARM64:
+    - Support read/write NEON registers.
+    - Support read/write NZCV registers.
+- Mips: Support read/write Mips64 registers.
+- X86: Support read/write MSR.
+- Haskell binding: update to the latest API.
+- Python: allow not having PATH setup.
+
+----------------------------------
+[Version 1.0]: February 23rd, 2017
+
+- Fix build script for BSD host.
+- Fix building Unicorn on Arm/PPC/Sparc/S390 hosts.
+- X86:
+    - Fix 16bit address computation.
+    - Fix initial state of segment registers.
+
+----------------------------------
+[Version 1.0-rc3]: January 25th, 2017
+
+- Rename API uc_context_free() to uc_free().
+- ARM:
+    - uc_reg_write() now can modify CPSR register.
+	- Add some ARM coproc registers.
+- ARM64: uc_reg_read|write() now handles W0-W31 registers.
+- Windows: fix a double free bug in uc_close().
+- New VB6 binding.
+- Java: update to support new APIs from v1.0-rc1.
+- Python:
+    - Fix memory leaking that prevents UC instances from being GC.
+    - Remove some dependencies leftover from glib time.
+	- Add new method mem_regions() (linked to uc_mem_regions() API)
+
+----------------------------------
+[Version 1.0-rc2]: January 4th, 2017
+
+- Remove glib & pkconfig dependency.
+- Python: fix an issue to restore support for FreeBSD (and other *BSD Unix).
+- ARM: support MCLASS cpu (Cortex-M3).
+- Windows: export a static lib that can be used outside of Mingw
+
+----------------------------------
+[Version 1.0-rc1]: December 22nd, 2016
+
+- Lots of bugfixes in all architectures.
+- Better support for ARM Thumb.
+- Fix many memory leaking issues.
+- New bindings: Haskell, MSVC.
+- Better support for Python3.
+- New APIs: uc_query, uc_reg_write_batch, uc_reg_read_batch, uc_mem_map_ptr, uc_mem_regions, uc_context_alloc, uc_context_save & uc_context_restore.
+- New memory hook type: UC_HOOK_MEM_READ_AFTER.
+- Add new version macros UC_VERSION_{MAJOR, MINOR, EXTRA}
+
+----------------------------------
+[Version 0.9]: October 15th, 2015
+
+- Initial public release.
+

mpcore/src/main/cpp/third_party/unicorn/README.md

@@ -0,0 +1,60 @@
+Unicorn Engine
+==============
+
+[![pypi downloads](https://pepy.tech/badge/unicorn)](https://pepy.tech/project/unicorn)
+[![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/unicorn.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:unicorn)
+
+
+<p align="center">
+<img width="250" src="docs/unicorn-logo.png">
+</p>
+
+Unicorn is a lightweight, multi-platform, multi-architecture CPU emulator framework, based on [QEMU](http://qemu.org).
+
+Unicorn offers some unparalleled features:
+
+- Multi-architecture: ARM, ARM64 (ARMv8), M68K, MIPS, PowerPC, RISCV, SPARC, S390X, TriCore and X86 (16, 32, 64-bit)
+- Clean/simple/lightweight/intuitive architecture-neutral API
+- Implemented in pure C language, with bindings for Crystal, Clojure, Visual Basic, Perl, Rust, Ruby, Python, Java, .NET, Go, Delphi/Free Pascal, Haskell, Pharo, Lua and Zig.
+- Native support for Windows & *nix (with Mac OSX, Linux, Android, *BSD & Solaris confirmed)
+- High performance via Just-In-Time compilation
+- Support for fine-grained instrumentation at various levels
+- Thread-safety by design
+- Distributed under free software license GPLv2
+
+Further information is available at http://www.unicorn-engine.org
+
+
+License
+-------
+
+This project is released under the [GPL license](COPYING).
+
+
+Compilation & Docs
+------------------
+
+See [docs/COMPILE.md](docs/COMPILE.md) file for how to compile and install Unicorn.
+
+More documentation is available in [docs/README.md](docs/README.md).
+
+For common questions, read [docs/FAQ.md](docs/FAQ.md) before raising an issue.
+
+Contact
+-------
+
+[Contact us](http://www.unicorn-engine.org/contact/) via mailing list, email or twitter for any questions.
+
+
+Join [our group](https://t.me/+lnNl0fPpyCYzZmVh) for instant feedback.
+
+Contribute
+----------
+
+If you want to contribute, please pick up something from our [Github issues](https://github.com/unicorn-engine/unicorn/issues).
+
+We also maintain a list of more challenged problems in [milestones](https://github.com/unicorn-engine/unicorn/milestones) for our regular release.
+
+Please send pull request to our [dev branch](https://github.com/unicorn-engine/unicorn/tree/dev).
+
+[CREDITS.TXT](CREDITS.TXT) records important contributors of our project.

mpcore/src/main/cpp/third_party/unicorn/SECURITY.md

@@ -0,0 +1,3 @@
+aquynh -at- gmail.com
+
+mio -at- lazym.io

mpcore/src/main/cpp/third_party/unicorn/TODO

@@ -0,0 +1 @@
+Moved to https://github.com/unicorn-engine/unicorn/milestones

mpcore/src/main/cpp/third_party/unicorn/build.rs

@@ -0,0 +1,390 @@
+use std::{env, path::PathBuf, process::Command};
+
+use bindgen::callbacks::{EnumVariantValue, ParseCallbacks};
+use heck::ToUpperCamelCase;
+
+fn ninja_available() -> bool {
+    Command::new("ninja").arg("--version").spawn().is_ok()
+}
+
+fn msvc_cmake_tools_available() -> bool {
+    Command::new("cmake").arg("--version").spawn().is_ok() && ninja_available()
+}
+
+fn get_tool_paths_msvc(compiler: &cc::Tool) -> Option<(PathBuf, PathBuf)> {
+    // If tools are already available, don't need to find them
+    if msvc_cmake_tools_available() {
+        return None;
+    }
+
+    let target = env::var("TARGET").unwrap();
+    let devenv = cc::windows_registry::find_tool(target.as_str(), "devenv");
+    let tool_root = devenv.map_or_else(
+        || {
+            // if devenv (i.e. Visual Studio) was not found, assume compiler is
+            // from standalone Build Tools and look there instead.
+            let tools_name = std::ffi::OsStr::new("BuildTools");
+            let compiler_path = compiler.path().to_path_buf();
+            compiler_path
+                .iter()
+                .find(|x| *x == tools_name)
+                .expect("Failed to find devenv or Build Tools");
+            compiler_path
+                .iter()
+                .take_while(|x| *x != tools_name)
+                .collect::<PathBuf>()
+                .join(tools_name)
+                .join(r"Common7\IDE")
+        },
+        |devenv_tool| devenv_tool.path().parent().unwrap().to_path_buf(),
+    );
+    let cmake_pkg_dir = tool_root.join(r"CommonExtensions\Microsoft\CMake");
+    let cmake_path = cmake_pkg_dir.join(r"CMake\bin\cmake.exe");
+    let ninja_path = cmake_pkg_dir.join(r"Ninja\ninja.exe");
+
+    assert!(cmake_path.is_file(), "missing cmake");
+    assert!(ninja_path.is_file(), "missing ninja");
+
+    Some((cmake_path, ninja_path))
+}
+
+fn build_with_cmake() {
+    let current_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap());
+    let uc_dir = current_dir;
+    let compiler = cc::Build::new().get_compiler();
+
+    // Initialize configuration
+    let mut config = cmake::Config::new(uc_dir);
+
+    // Check for tools and set up configuration
+    let has_ninja = if compiler.is_like_msvc() {
+        // MSVC-specific setup
+        if let Some((cmake_path, ninja_path)) = get_tool_paths_msvc(&compiler) {
+            // Tell Cargo where to find the tools instead of modifying PATH
+            println!("cargo:rustc-env=CMAKE_PATH={}", cmake_path.display());
+            println!("cargo:rustc-env=NINJA_PATH={}", ninja_path.display());
+
+            // Set cmake path for the cmake crate
+            config.define("CMAKE_PROGRAM", cmake_path.to_str().unwrap());
+        }
+        true
+    } else {
+        // Non-MSVC setup
+        ninja_available()
+    };
+
+    // Configure build generator
+    if has_ninja {
+        config.generator("Ninja");
+    }
+
+    let mut archs = String::new();
+
+    if std::env::var("CARGO_FEATURE_ARCH_X86").is_ok() {
+        archs.push_str("x86;");
+    }
+    if std::env::var("CARGO_FEATURE_ARCH_ARM").is_ok() {
+        archs.push_str("arm;");
+    }
+    if std::env::var("CARGO_FEATURE_ARCH_AARCH64").is_ok() {
+        archs.push_str("aarch64;");
+    }
+    if std::env::var("CARGO_FEATURE_ARCH_RISCV").is_ok() {
+        archs.push_str("riscv;");
+    }
+    if std::env::var("CARGO_FEATURE_ARCH_MIPS").is_ok() {
+        archs.push_str("mips;");
+    }
+    if std::env::var("CARGO_FEATURE_ARCH_SPARC").is_ok() {
+        archs.push_str("sparc;");
+    }
+    if std::env::var("CARGO_FEATURE_ARCH_M68K").is_ok() {
+        archs.push_str("m68k;");
+    }
+    if std::env::var("CARGO_FEATURE_ARCH_PPC").is_ok() {
+        archs.push_str("ppc;");
+    }
+    if std::env::var("CARGO_FEATURE_ARCH_S390X").is_ok() {
+        archs.push_str("s390x;");
+    }
+    if std::env::var("CARGO_FEATURE_ARCH_TRICORE").is_ok() {
+        archs.push_str("tricore;");
+    }
+
+    if !archs.is_empty() {
+        archs.pop();
+    }
+
+    if config.get_profile() == "Debug" {
+        config.define("UNICORN_LOGGING", "ON");
+    }
+
+    let dst = config
+        .define("UNICORN_BUILD_TESTS", "OFF")
+        .define("UNICORN_INSTALL", "ON")
+        .define("UNICORN_ARCH", archs)
+        .build();
+
+    println!(
+        "cargo:rustc-link-search=native={}",
+        dst.join("lib").display()
+    );
+    // rhel
+    println!(
+        "cargo:rustc-link-search=native={}",
+        dst.join("lib64").display()
+    );
+
+    // Lazymio(@wtdcode): Dynamic link may break. See: https://github.com/rust-lang/cargo/issues/5077
+    if cfg!(feature = "dynamic_linkage") {
+        if compiler.is_like_msvc() {
+            println!("cargo:rustc-link-lib=dylib=unicorn-import");
+        } else {
+            println!("cargo:rustc-link-lib=dylib=unicorn");
+        }
+    } else {
+        println!("cargo:rustc-link-lib=static=unicorn");
+    }
+    if !compiler.is_like_msvc() {
+        println!("cargo:rustc-link-lib=pthread");
+        println!("cargo:rustc-link-lib=m");
+    }
+}
+
+fn watch_source_files() {
+    let current_dir = std::env::var("CARGO_MANIFEST_DIR").unwrap();
+    let project_root = std::path::Path::new(&current_dir)
+        .parent()
+        .unwrap()
+        .parent()
+        .unwrap()
+        .parent()
+        .unwrap();
+
+    println!(
+        "cargo:rerun-if-changed={}",
+        project_root.join("uc.c").display()
+    );
+    println!(
+        "cargo:rerun-if-changed={}",
+        project_root.join("list.c").display()
+    );
+
+    // Directories to watch for changes
+    let watch_dirs = vec!["qemu", "include", "bindings", "glib_compat"];
+
+    let watch_extensions = vec![".c", ".h"];
+
+    for dir in watch_dirs {
+        let dir_path = project_root.join(dir);
+        if dir_path.exists() {
+            register_dir_files(&dir_path, &watch_extensions);
+        }
+    }
+}
+
+fn register_dir_files(dir: &std::path::Path, extensions: &[&str]) {
+    if let Ok(entries) = std::fs::read_dir(dir) {
+        for entry in entries.filter_map(Result::ok) {
+            let path = entry.path();
+            if path.is_dir() {
+                register_dir_files(&path, extensions);
+            } else if let Some(ext) = path.extension() {
+                if extensions
+                    .iter()
+                    .any(|&e| e == format!(".{}", ext.to_string_lossy()))
+                {
+                    println!("cargo:rerun-if-changed={}", path.display());
+                }
+            }
+        }
+    }
+}
+
+#[derive(Debug)]
+struct Renamer;
+
+impl ParseCallbacks for Renamer {
+    fn item_name(&self, original_item_name: &str) -> Option<String> {
+        // Special case for error type
+        if original_item_name == "uc_err" {
+            return Some(String::from("uc_error"));
+        }
+
+        if original_item_name.contains("_cpu_") {
+            return original_item_name
+                .strip_prefix("uc_cpu_")
+                .map(|suffix| format!("{}CpuModel", suffix.to_upper_camel_case()));
+        }
+
+        if original_item_name.ends_with("_reg") {
+            return original_item_name
+                .strip_prefix("uc_")
+                .and_then(|suffix| suffix.strip_suffix("_reg"))
+                .map(|suffix| format!("Register{}", suffix.replace('_', "").to_uppercase()));
+        }
+
+        if original_item_name.ends_with("_insn") {
+            return original_item_name
+                .strip_prefix("uc_")
+                .and_then(|suffix| suffix.strip_suffix("_insn"))
+                .map(|suffix| format!("{}Insn", suffix.to_upper_camel_case()));
+        }
+
+        if original_item_name.contains("_mode_") {
+            return original_item_name
+                .strip_prefix("uc_mode_")
+                .map(|suffix| format!("{}Mode", suffix.to_upper_camel_case()));
+        }
+
+        // Map various specific types to more idiomatic Rust names
+        match original_item_name {
+            "uc_query_type" => Some(String::from("Query")),
+            "uc_tlb_type" => Some(String::from("TlbType")),
+            "uc_mem_type" => Some(String::from("MemType")),
+            "uc_tb" => Some(String::from("TranslationBlock")),
+            "uc_arch" => Some(String::from("Arch")),
+            "uc_mode" => Some(String::from("Mode")),
+            "uc_mem_region" => Some(String::from("MemRegion")),
+            "uc_prot" => Some(String::from("Prot")),
+            "uc_hook_type" => Some(String::from("HookType")),
+            "uc_tlb_entry" => Some(String::from("TlbEntry")),
+            "uc_control_type" => Some(String::from("ControlType")),
+            "uc_context_content" => Some(String::from("ContextMode")),
+            "uc_tcg_op_code" => Some(String::from("TcgOpCode")),
+            "uc_tcg_op_flag" => Some(String::from("TcgOpFlag")),
+            _ => None,
+        }
+    }
+
+    fn enum_variant_name(
+        &self,
+        enum_name: Option<&str>,
+        original_variant_name: &str,
+        _variant_value: EnumVariantValue,
+    ) -> Option<String> {
+        if let Some(enum_name) = enum_name {
+            if enum_name.starts_with("enum uc_") {
+                // Prefix to strip from enum variant names
+                let prefix = match enum_name.strip_prefix("enum uc_").unwrap() {
+                    "query_type" => "UC_QUERY",
+                    "tlb_type" => "UC_TLB",
+                    "control_type" => "UC_CTL",
+                    "context_content" => "UC_CTL_CONTEXT",
+                    "err" => "UC_ERR",
+                    "mem_type" | "mem_region" => "UC_MEM",
+                    "arch" => "UC_ARCH",
+                    "mode" => "UC_MODE",
+                    "prot" => "UC_PROT",
+                    "hook_type" => "UC_HOOK",
+                    "x86_insn" => "UC_X86_INS",
+                    "tcg_op_code" => "UC_TCG_OP",
+                    "tcg_op_flag" => "UC_TCG_OP_FLAG",
+                    other => format!("UC_{}", other.to_uppercase()).leak(),
+                }
+                .to_string()
+                    + "_";
+
+                // Strip prefix
+                let mut fixed = original_variant_name
+                    .strip_prefix(&prefix)
+                    .map(str::to_uppercase);
+
+                // Special handling for numeric register names in PPC and MIPS
+                if (enum_name == "enum uc_ppc_reg" || enum_name == "enum uc_mips_reg")
+                    && fixed.as_ref().is_some_and(|s| s.parse::<u32>().is_ok())
+                {
+                    fixed = fixed.map(|s| format!("R{s}"));
+                }
+
+                // Special handling for CPU variants that start with a number
+                if enum_name.contains("cpu")
+                    && fixed
+                        .as_ref()
+                        .is_some_and(|s| s.chars().next().unwrap().is_ascii_digit())
+                {
+                    fixed = fixed.map(|s| format!("Model_{s}"));
+                }
+
+                // Special handling for mode values
+                if enum_name == "enum uc_mode" {
+                    fixed = fixed.map(|s| match s.as_str() {
+                        "16" | "32" | "64" => format!("MODE_{s}"),
+                        _ => s,
+                    });
+                }
+
+                return fixed;
+            }
+        }
+
+        None
+    }
+}
+
+fn generate_bindings() {
+    const HEADER_PATH: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/include/unicorn/unicorn.h");
+
+    let bitflag_enums = [
+        "uc_hook_type",
+        "uc_tcg_op_flag",
+        "uc_prot",
+        "uc_mode",
+        "uc_context_content",
+        "uc_control_type",
+    ];
+
+    let bindings = bindgen::Builder::default()
+        .header(HEADER_PATH)
+        .layout_tests(false)
+        .allowlist_type("^uc.*")
+        .allowlist_function("^uc_.*")
+        .allowlist_var("^uc.*")
+        .rustified_enum("^uc.*")
+        .prepend_enum_name(false)
+        .parse_callbacks(Box::new(Renamer))
+        .bitfield_enum(bitflag_enums.join("|"))
+        .derive_ord(true)
+        .derive_eq(true)
+        .use_core()
+        .generate()
+        .expect("Failed to generate bindings");
+
+    let bindings_rs = PathBuf::from(std::env::var("OUT_DIR").unwrap()).join("bindings.rs");
+    bindings
+        .write_to_file(&bindings_rs)
+        .unwrap_or_else(|_| panic!("Failed to write bindings into path: {bindings_rs:?}"));
+}
+
+fn main() {
+    watch_source_files();
+
+    generate_bindings();
+
+    match pkg_config::Config::new()
+        .atleast_version("2")
+        .cargo_metadata(false)
+        .probe("unicorn")
+    {
+        Ok(lib) => {
+            for dir in lib.link_paths {
+                println!("cargo:rustc-link-search=native={}", dir.to_str().unwrap());
+            }
+            if cfg!(feature = "dynamic_linkage") {
+                if cc::Build::new().get_compiler().is_like_msvc() {
+                    println!("cargo:rustc-link-lib=dylib=unicorn-import");
+                } else {
+                    println!("cargo:rustc-link-lib=dylib=unicorn");
+                }
+            } else {
+                println!("cargo:rustc-link-arg=-Wl,-allow-multiple-definition");
+                println!("cargo:rustc-link-lib=static=unicorn");
+                println!("cargo:rustc-link-lib=pthread");
+                println!("cargo:rustc-link-lib=m");
+            }
+        }
+        Err(_) => {
+            build_with_cmake();
+        }
+    }
+}

mpcore/src/main/cpp/third_party/unicorn/build.zig

@@ -0,0 +1,266 @@
+//! License: GNU GENERAL PUBLIC LICENSE Version 2
+
+const std = @import("std");
+const MIN_ZIG_VERSION: []const u8 = "0.13.0";
+const MIN_ZIG_VERSION_ERR_MSG = "Please! Update zig toolchain to >= v" ++ MIN_ZIG_VERSION;
+
+const SampleFileTypes = enum {
+    c,
+    cpp,
+    zig,
+};
+
+const SampleDescripton = struct {
+    file_type: SampleFileTypes,
+    root_file_path: []const u8,
+};
+
+/// Create a module for the Zig Bindings
+///
+/// This will also get exported as a library that other zig projects can use
+/// as a dependency via the zig build system.
+fn create_unicorn_sys(b: *std.Build, target: std.Build.ResolvedTarget, optimize: std.builtin.OptimizeMode) *std.Build.Module {
+    const unicorn_sys = b.addModule("unicorn-sys", .{
+        .target = target,
+        .optimize = optimize,
+        .root_source_file = b.path("bindings/zig/unicorn/unicorn.zig"),
+    });
+
+    // link libc
+    unicorn_sys.link_libc = true;
+
+    // we need the c header for the zig-bindings
+    unicorn_sys.addIncludePath(b.path("include"));
+    unicorn_sys.addLibraryPath(b.path("build"));
+
+    // Linking to the Unicorn library
+    if (target.result.abi == .msvc and target.result.os.tag == .windows) {
+        unicorn_sys.linkSystemLibrary("unicorn.dll", .{});
+    } else {
+        unicorn_sys.linkSystemLibrary("unicorn", .{});
+    }
+
+    return unicorn_sys;
+}
+
+// Although this function looks imperative, note that its job is to
+// declaratively construct a build graph that will be executed by an external
+// runner.
+pub fn build(b: *std.Build) void {
+    if (comptime !checkVersion())
+        @compileError(MIN_ZIG_VERSION_ERR_MSG);
+
+    // Standard target options allows the person running `zig build` to choose
+    // what target to build for. Here we do not override the defaults, which
+    // means any target is allowed, and the default is native. Other options
+    // for restricting supported target set are available.
+    const target = b.standardTargetOptions(.{});
+
+    // Standard optimization options allow the person running `zig build` to select
+    // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. Here we do not
+    // set a preferred release mode, allowing the user to decide how to optimize.
+    const optimize = b.standardOptimizeOption(.{});
+
+    // Give the user the options to perform the cmake build in parallel or not
+    // (eg. ci on macos will fail if parallel is enabled)
+    //
+    // flag: -Dparallel=true/false
+    const parallel_cmake = b.option(bool, "parallel", "Enable parallel cmake build") orelse true;
+
+    // flag: -DSamples=True/False
+    const samples = b.option(bool, "Samples", "Build all Samples [default: true]") orelse true;
+
+    const sample_bins = [_]SampleDescripton{
+        .{ .file_type = .zig, .root_file_path = "bindings/zig/sample/sample_riscv_zig.zig" },
+        .{ .file_type = .c, .root_file_path = "samples/sample_arm.c" },
+        .{ .file_type = .c, .root_file_path = "samples/sample_arm64.c" },
+        .{ .file_type = .c, .root_file_path = "samples/sample_ctl.c" },
+        .{ .file_type = .c, .root_file_path = "samples/sample_batch_reg.c" },
+        .{ .file_type = .c, .root_file_path = "samples/sample_m68k.c" },
+        .{ .file_type = .c, .root_file_path = "samples/sample_riscv.c" },
+        .{ .file_type = .c, .root_file_path = "samples/sample_sparc.c" },
+        .{ .file_type = .c, .root_file_path = "samples/sample_s390x.c" },
+        .{ .file_type = .c, .root_file_path = "samples/shellcode.c" },
+        .{ .file_type = .c, .root_file_path = "samples/sample_tricore.c" },
+        .{ .file_type = .c, .root_file_path = "samples/sample_x86.c" },
+        .{ .file_type = .c, .root_file_path = "samples/sample_x86_32_gdt_and_seg_regs.c" },
+    };
+
+    // make a module for Zig Bindings
+    const unicorn_sys = create_unicorn_sys(b, target, optimize);
+
+    // Build Samples
+    if (samples) {
+        for (sample_bins) |sample| {
+            const sample_bin = buildExe(b, .{
+                .target = target,
+                .optimize = optimize,
+                .filetype = sample.file_type,
+                .filepath = sample.root_file_path,
+            });
+
+            // import the unicorn sys module if this is a zig build
+            if (sample.file_type == .zig) {
+                sample_bin.root_module.addImport("unicorn", unicorn_sys);
+            }
+        }
+    }
+
+    // CMake Build
+    const cmake = cmakeBuild(b, parallel_cmake);
+    const cmake_step = b.step("cmake", "Run cmake build");
+    cmake_step.dependOn(&cmake.step);
+}
+
+fn buildExe(b: *std.Build, info: BuildInfo) *std.Build.Step.Compile {
+    const target = info.stdTarget();
+
+    const execonfig: std.Build.ExecutableOptions = switch (info.filetype) {
+        .c, .cpp => .{
+            .name = info.filename(),
+            .target = info.target,
+            .optimize = info.optimize,
+        },
+        else => .{
+            .name = info.filename(),
+            .target = info.target,
+            .optimize = info.optimize,
+            .root_source_file = b.path(info.filepath),
+        },
+    };
+    const exe = b.addExecutable(execonfig);
+
+    if (info.filetype != .zig) {
+        exe.addCSourceFile(.{
+            .file = b.path(info.filepath),
+            .flags = &.{
+                "-Wall",
+                "-Werror",
+                "-fno-sanitize=all",
+                "-Wshadow",
+            },
+        });
+
+        // Ensure the C headers are available
+        exe.addIncludePath(b.path("include"));
+
+        // Ensure the C library is available
+        exe.addLibraryPath(b.path("build"));
+
+        // linking to OS-LibC or static-linking for:
+        // Musl(Linux) [e.g: -Dtarget=native-linux-musl]
+        // MinGW(Windows) [e.g: -Dtarget=native-windows-gnu (default)]
+        if (info.filetype == .cpp and target.abi != .msvc)
+            exe.linkLibCpp() // static-linking LLVM-libcxx (all targets) + libC
+        else
+            exe.linkLibC();
+
+        // Now link the C library
+        if (target.abi == .msvc and target.os.tag == .windows) {
+            exe.linkSystemLibrary("unicorn.dll");
+        } else exe.linkSystemLibrary("unicorn");
+    }
+
+    // Linking to the Unicorn library
+    if (target.abi == .msvc and target.os.tag == .windows) {
+        exe.want_lto = false;
+    }
+
+    // This declares intent for the executable to be installed into the
+    // standard location when the user invokes the "install" step (the default
+    // step when running `zig build`).
+    b.installArtifact(exe);
+
+    // This *creates* a RunStep in the build graph, to be executed when another
+    // step is evaluated that depends on it. The next line below will establish
+    // such a dependency.
+    const run_cmd = b.addRunArtifact(exe);
+
+    // By making the run step depend on the install step, it will be run from the
+    // installation directory rather than directly from within the cache directory.
+    // This is not necessary, however, if the application depends on other installed
+    // files, this ensures they will be present and in the expected location.
+    run_cmd.step.dependOn(b.getInstallStep());
+
+    // This allows the user to pass arguments to the application in the build
+    // command itself, like this: `zig build run -- arg1 arg2 etc`
+    if (b.args) |args| {
+        run_cmd.addArgs(args);
+    }
+
+    // This creates a build step. It will be visible in the `zig build --help` menu,
+    // and can be selected like this: `zig build run`
+    // This will evaluate the `run` step rather than the default, which is "install".
+    const run_step = b.step(info.filename(), b.fmt("Run the {s}.", .{info.filename()}));
+    run_step.dependOn(&run_cmd.step);
+
+    return exe;
+}
+
+const PARALLEL_CMAKE_COMMAND = [_][]const u8{
+    "cmake",
+    "--build",
+    "build",
+    "--config",
+    "release",
+    "--parallel",
+};
+
+const SINGLE_CMAKE_COMMAND = [_][]const u8{
+    "cmake",
+    "--build",
+    "build",
+    "--config",
+    "release",
+};
+fn cmakeBuild(b: *std.Build, parallel_cmake: bool) *std.Build.Step.Run {
+    const preconf = b.addSystemCommand(&.{
+        "cmake",
+        "-B",
+        "build",
+        "-DZIG_BUILD=ON",
+        "-DUNICORN_BUILD_TESTS=OFF",
+        "-DUNICORN_INSTALL=OFF",
+        "-DCMAKE_BUILD_TYPE=Release",
+    });
+
+    // build in parallel if requested
+    const cmakebuild = b.addSystemCommand(blk: {
+        if (parallel_cmake) {
+            break :blk &PARALLEL_CMAKE_COMMAND;
+        } else {
+            break :blk &SINGLE_CMAKE_COMMAND;
+        }
+    });
+    cmakebuild.step.dependOn(&preconf.step);
+    return cmakebuild;
+}
+
+// ensures the currently in-use zig version is at least the minimum required
+fn checkVersion() bool {
+    const builtin = @import("builtin");
+    if (!@hasDecl(builtin, "zig_version")) {
+        return false;
+    }
+
+    const needed_version = std.SemanticVersion.parse(MIN_ZIG_VERSION) catch unreachable;
+    const version = builtin.zig_version;
+    const order = version.order(needed_version);
+    return order != .lt;
+}
+
+const BuildInfo = struct {
+    filepath: []const u8,
+    filetype: SampleFileTypes,
+    target: std.Build.ResolvedTarget,
+    optimize: std.builtin.OptimizeMode,
+
+    fn filename(self: BuildInfo) []const u8 {
+        var split = std.mem.splitSequence(u8, std.fs.path.basename(self.filepath), ".");
+        return split.first();
+    }
+
+    fn stdTarget(self: *const BuildInfo) std.Target {
+        return self.target.result;
+    }
+};

mpcore/src/main/cpp/third_party/unicorn/build.zig.zon

@@ -0,0 +1,7 @@
+.{
+    .name = .unicorn,
+    .version = "2.1.4",
+    .minimum_zig_version = "0.14.0-dev.3445+6c3cbb0c8",
+    .fingerprint = 0x58fbd83f3bf465b6,
+    .paths = .{""},
+}

mpcore/src/main/cpp/third_party/unicorn/cmake/bundle_static.cmake

@@ -0,0 +1,57 @@
+# https://cristianadam.eu/20190501/bundling-together-static-libraries-with-cmake/
+function(bundle_static_library tgt_name bundled_tgt_name library_name)
+  list(APPEND static_libs ${tgt_name})
+  set(dep_libs "")
+
+  function(_recursively_collect_dependencies input_target)
+    set(_input_link_libraries LINK_LIBRARIES)
+    get_target_property(_input_type ${input_target} TYPE)
+    if (${_input_type} STREQUAL "INTERFACE_LIBRARY")
+      set(_input_link_libraries INTERFACE_LINK_LIBRARIES)
+    endif()
+    get_target_property(public_dependencies ${input_target} ${_input_link_libraries})
+    foreach(dependency IN LISTS public_dependencies)
+      if(TARGET ${dependency})
+        get_target_property(alias ${dependency} ALIASED_TARGET)
+        if (TARGET ${alias})
+          set(dependency ${alias})
+        endif()
+        get_target_property(_type ${dependency} TYPE)
+        if (${_type} STREQUAL "STATIC_LIBRARY")
+          list(APPEND static_libs ${dependency})
+        endif()
+
+        get_property(library_already_added
+          GLOBAL PROPERTY _${tgt_name}_static_bundle_${dependency})
+        if (NOT library_already_added)
+          set_property(GLOBAL PROPERTY _${tgt_name}_static_bundle_${dependency} ON)
+          _recursively_collect_dependencies(${dependency})
+        endif()
+      elseif(dependency)
+        list(APPEND dep_libs ${dependency})
+      endif()
+    endforeach()
+    set(static_libs ${static_libs} PARENT_SCOPE)
+    set(dep_libs ${dep_libs} PARENT_SCOPE)
+  endfunction()
+
+  _recursively_collect_dependencies(${tgt_name})
+
+  list(REMOVE_DUPLICATES static_libs)
+  list(REMOVE_DUPLICATES dep_libs)
+
+  foreach(tgt IN LISTS static_libs)
+    list(APPEND static_libs_objects $<TARGET_OBJECTS:${tgt}>)
+  endforeach()
+
+  add_library(${bundled_tgt_name} STATIC ${static_libs_objects})
+  set_target_properties(${bundled_tgt_name} PROPERTIES
+    INTERFACE_INCLUDE_DIRECTORIES $<TARGET_PROPERTY:${tgt_name},INTERFACE_INCLUDE_DIRECTORIES>
+    INTERFACE_LINK_LIBRARIES "${dep_libs}"
+    OUTPUT_NAME "${library_name}"
+    SYMLINK_NAME "${library_name}.o"
+  )
+  add_custom_command(TARGET ${bundled_tgt_name} POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E create_symlink "$<TARGET_FILE_NAME:${bundled_tgt_name}>" "$<TARGET_FILE_DIR:${bundled_tgt_name}>/$<TARGET_PROPERTY:${bundled_tgt_name},SYMLINK_NAME>"
+  )
+endfunction()

mpcore/src/main/cpp/third_party/unicorn/cmake/mingw-w64.cmake

@@ -0,0 +1,17 @@
+# cross compile
+SET(CMAKE_SYSTEM_NAME Windows)
+
+# set the compiler
+SET(CMAKE_C_COMPILER  x86_64-w64-mingw32-gcc)
+SET(CMAKE_CXX_COMPILER x86_64-w64-mingw32-g++)
+SET(CMAKE_RC_COMPILER x86_64-w64-mingw32-windres)
+
+# set the compiler search path
+SET(CMAKE_FIND_ROOT_PATH  /usr/x86_64-w64-mingw32)
+
+# adjust the default behaviour of the FIND_XXX() commands:
+# search headers and libraries in the target environment, search 
+# programs in the host environment
+set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)

mpcore/src/main/cpp/third_party/unicorn/cmake/zig.cmake

@@ -0,0 +1,9 @@
+set(CMAKE_CROSSCOMPILING TRUE)
+# set the compiler
+if(WIN32)
+    SET(ZIG_CC ${CMAKE_SOURCE_DIR}/bindings/zig/tools/zigcc.cmd)
+else()
+    SET(ZIG_CC ${CMAKE_SOURCE_DIR}/bindings/zig/tools/zigcc.sh)
+endif()
+SET(CMAKE_C_COMPILER_ID ${ZIG_CC})
+SET(CMAKE_C_COMPILER ${ZIG_CC})

mpcore/src/main/cpp/third_party/unicorn/format.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+find . -maxdepth 1 "(" -name "*.c" -or -name "*.h" ")" -exec clang-format -i -style=file "{}" ";"
+find ./msvc -maxdepth 1 "(" -name "*.c" -or -name "*.h" ")" -exec clang-format -i -style=file "{}" ";"
+find ./include -maxdepth 2 "(" -name "*.c" -or -name "*.h" ")" -exec clang-format -i -style=file "{}" ";"
+find ./tests/unit -maxdepth 1 "(" -name "*.c" -or -name "*.h" ")" -exec clang-format -i -style=file "{}" ";"
+find ./samples -maxdepth 1 "(" -name "*.c" -or -name "*.h" ")" -exec clang-format -i -style=file "{}" ";"
+find ./qemu "(" -name "unicorn.c" -or -name "unicorn.h" -or -name "unicorn_arm.c" -or -name "unicorn_aarch64.c" ")" -exec clang-format -i -style=file "{}" ";"

mpcore/src/main/cpp/third_party/unicorn/glib_compat/README

@@ -0,0 +1,2 @@
+This is a compatible glib library, customized for Unicorn.
+Based on glib 2.64.4.

mpcore/src/main/cpp/third_party/unicorn/glib_compat/garray.h

@@ -0,0 +1,99 @@
+/* GLIB - Library of useful routines for C programming
+ * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
+ */
+
+/*
+ * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
+ * file for a list of people on the GLib Team.  See the ChangeLog
+ * files for a list of changes.  These files are distributed with
+ * GLib at ftp://ftp.gtk.org/pub/gtk/.
+ */
+
+#ifndef __G_ARRAY_H__
+#define __G_ARRAY_H__
+
+#include "gtypes.h"
+
+typedef struct _GBytes      GBytes;
+typedef struct _GArray		GArray;
+typedef struct _GByteArray	GByteArray;
+typedef struct _GPtrArray	GPtrArray;
+
+struct _GArray
+{
+    gchar *data;
+    guint len;
+};
+
+struct _GByteArray
+{
+    guint8 *data;
+    guint	  len;
+};
+
+struct _GPtrArray
+{
+    gpointer *pdata;
+    guint	    len;
+};
+
+/* Resizable arrays. remove fills any cleared spot and shortens the
+ * array, while preserving the order. remove_fast will distort the
+ * order by moving the last element to the position of the removed.
+ */
+
+#define g_array_append_val(a,v)	  g_array_append_vals (a, &(v), 1)
+#define g_array_index(a,t,i)      (((t*) (void *) (a)->data) [(i)])
+
+GArray* g_array_append_vals (GArray *array,
+        gconstpointer data,
+        guint         len);
+
+GArray* g_array_new (gboolean zero_terminated, gboolean clear_, guint element_size);
+GArray* g_array_sized_new (gboolean zero_terminated,
+        gboolean clear_,
+        guint    element_size,
+        guint    reserved_size);
+
+gchar*  g_array_free(GArray *array, gboolean free_segment);
+GArray* g_array_set_size(GArray *array, guint length);
+GArray*
+g_array_remove_range (GArray *farray,
+        guint   index_,
+        guint   length);
+
+void g_ptr_array_set_free_func (GPtrArray *array,
+        GDestroyNotify element_free_func);
+
+/* Resizable pointer array.  This interface is much less complicated
+ * than the above.  Add appends a pointer.  Remove fills any cleared 
+ * spot and shortens the array. remove_fast will again distort order.  
+ */
+#define    g_ptr_array_index(array,index_) ((array)->pdata)[index_]
+GPtrArray* g_ptr_array_new_with_free_func (GDestroyNotify element_free_func);
+void       g_ptr_array_add(GPtrArray *array, gpointer data);
+GPtrArray* g_ptr_array_sized_new (guint reserved_size);
+GPtrArray* g_ptr_array_remove_range (GPtrArray *array, guint index_, guint length);
+
+/* Byte arrays, an array of guint8.  Implemented as a GArray,
+ * but type-safe.
+ */
+GByteArray* g_byte_array_sized_new(guint reserved_size);
+guint8*     g_byte_array_free(GByteArray *array, gboolean free_segment);
+GByteArray* g_byte_array_append(GByteArray *array, const guint8 *data, guint len);
+GByteArray* g_byte_array_set_size(GByteArray *array, guint length);
+
+#endif /* __G_ARRAY_H__ */

mpcore/src/main/cpp/third_party/unicorn/glib_compat/ghash.h

@@ -0,0 +1,77 @@
+/* GLIB - Library of useful routines for C programming
+ * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
+ */
+
+/*
+ * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
+ * file for a list of people on the GLib Team.  See the ChangeLog
+ * files for a list of changes.  These files are distributed with
+ * GLib at ftp://ftp.gtk.org/pub/gtk/.
+ */
+
+#ifndef __G_HASH_H__
+#define __G_HASH_H__
+
+#include "gtypes.h"
+
+typedef struct _GHashTable GHashTable;
+
+typedef gboolean (*GHRFunc) (gpointer key, gpointer value, gpointer user_data);
+
+struct _GHashTableIter
+{
+    /*< private >*/
+    gpointer      dummy1;
+    gpointer      dummy2;
+    gpointer      dummy3;
+    int           dummy4;
+    gboolean      dummy5;
+    gpointer      dummy6;
+};
+
+GHashTable* g_hash_table_new (GHashFunc hash_func, GEqualFunc key_equal_func);
+
+GHashTable* g_hash_table_new_full (GHashFunc hash_func,
+        GEqualFunc      key_equal_func,
+        GDestroyNotify  key_destroy_func,
+        GDestroyNotify  value_destroy_func);
+
+void g_hash_table_destroy (GHashTable *hash_table);
+
+gboolean g_hash_table_insert (GHashTable *hash_table, gpointer key, gpointer value);
+
+void g_hash_table_replace (GHashTable *hash_table, gpointer key, gpointer value);
+
+gboolean g_hash_table_remove (GHashTable *hash_table, gconstpointer key);
+
+void g_hash_table_remove_all (GHashTable *hash_table);
+
+gpointer g_hash_table_lookup (GHashTable *hash_table, gconstpointer key);
+
+void g_hash_table_foreach (GHashTable *hash_table, GHFunc func, gpointer user_data);
+
+guint g_hash_table_size (GHashTable *hash_table);
+
+GHashTable* g_hash_table_ref (GHashTable *hash_table);
+
+void g_hash_table_unref (GHashTable *hash_table);
+
+/* Hash Functions
+ */
+gboolean g_int_equal (gconstpointer v1, gconstpointer v2);
+guint    g_int_hash (gconstpointer v);
+
+#endif /* __G_HASH_H__ */

mpcore/src/main/cpp/third_party/unicorn/glib_compat/glib_compat.h

@@ -0,0 +1,97 @@
+/*
+glib_compat.h replacement functionality for glib code used in qemu
+Copyright (C) 2016 Chris Eagle cseagle at gmail dot com
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+of the License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+*/
+
+#ifndef __GLIB_COMPAT_H
+#define __GLIB_COMPAT_H
+
+#include "unicorn/platform.h"
+#include <stdarg.h>
+#include <stdlib.h>
+#include <assert.h>
+
+#define G_MAXUINT UINT_MAX
+#define G_MAXINT  INT_MAX
+
+#include "gtestutils.h"
+#include "gtypes.h"
+#include "garray.h"
+#include "gtree.h"
+#include "ghash.h"
+#include "gmem.h"
+#include "gslice.h"
+#include "gmessages.h"
+#include "gpattern.h"
+#include "grand.h"
+#include "glist.h"
+#include "gnode.h"
+
+typedef gint (*GCompareDataFunc)(gconstpointer a,
+                gconstpointer b,
+                gpointer user_data);
+typedef void (*GFunc)(gpointer data, gpointer user_data);
+typedef gint (*GCompareFunc)(gconstpointer v1, gconstpointer v2);
+
+guint g_str_hash(gconstpointer v);
+gboolean g_str_equal(gconstpointer v1, gconstpointer v2);
+guint g_int_hash(gconstpointer v);
+
+gboolean g_int_equal(gconstpointer v1, gconstpointer v2);
+
+int g_strcmp0(const char *str1, const char *str2);
+
+GList *g_list_first(GList *list);
+void g_list_foreach(GList *list, GFunc func, gpointer user_data);
+void g_list_free(GList *list);
+GList *g_list_insert_sorted(GList *list, gpointer data, GCompareFunc compare);
+#define g_list_next(list) (list->next)
+GList *g_list_prepend(GList *list, gpointer data);
+GList *g_list_remove_link(GList *list, GList *llink);
+GList *g_list_sort(GList *list, GCompareFunc compare);
+
+typedef struct _GSList {
+  gpointer data;
+  struct _GSList *next;
+} GSList;
+
+GSList *g_slist_append(GSList *list, gpointer data);
+void g_slist_foreach(GSList *list, GFunc func, gpointer user_data);
+void g_slist_free(GSList *list);
+GSList *g_slist_prepend(GSList *list, gpointer data);
+GSList *g_slist_sort(GSList *list, GCompareFunc compare);
+GSList *g_slist_find_custom(GSList *list, gconstpointer data, GCompareFunc func);
+
+/* replacement for g_malloc dependency */
+void g_free(gpointer ptr);
+gpointer g_realloc(gpointer ptr, size_t size);
+
+char *g_strdup(const char *str);
+char *g_strdup_printf(const char *format, ...);
+char *g_strdup_vprintf(const char *format, va_list ap);
+char *g_strndup(const char *str, size_t n);
+void g_strfreev(char **v);
+gpointer g_memdup(gconstpointer mem, size_t byte_size);
+gpointer g_new_(size_t sz, size_t n_structs);
+gpointer g_new0_(size_t sz, size_t n_structs);
+gpointer g_renew_(size_t sz, gpointer mem, size_t n_structs);
+
+gchar** g_strsplit (const gchar *string,
+            const gchar *delimiter,
+            gint         max_tokens);
+
+#endif

mpcore/src/main/cpp/third_party/unicorn/glib_compat/glist.c

@@ -0,0 +1,154 @@
+/* GLIB - Library of useful routines for C programming
+ * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
+ */
+
+/*
+ * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
+ * file for a list of people on the GLib Team.  See the ChangeLog
+ * files for a list of changes.  These files are distributed with
+ * GLib at ftp://ftp.gtk.org/pub/gtk/.
+ */
+
+/*
+ * MT safe
+ */
+
+#include "gtypes.h"
+#include "glist.h"
+#include "gslice.h"
+#include "gmessages.h"
+
+#define _g_list_alloc()         g_slice_new (GList)
+#define _g_list_alloc0()        g_slice_new0 (GList)
+#define _g_list_free1(list)     g_slice_free (GList, list)
+
+/**
+ * g_list_alloc:
+ *
+ * Allocates space for one #GList element. It is called by
+ * g_list_append(), g_list_prepend(), g_list_insert() and
+ * g_list_insert_sorted() and so is rarely used on its own.
+ *
+ * Returns: a pointer to the newly-allocated #GList element
+ **/
+GList *g_list_alloc (void)
+{
+    return _g_list_alloc0 ();
+}
+
+static inline GList *_g_list_remove_link (GList *list, GList *link)
+{
+    if (link == NULL)
+        return list;
+
+    if (link->prev)
+    {
+        if (link->prev->next == link)
+            link->prev->next = link->next;
+        //else
+        //  g_warning ("corrupted double-linked list detected");
+    }
+    if (link->next)
+    {
+        if (link->next->prev == link)
+            link->next->prev = link->prev;
+        //else
+        //  g_warning ("corrupted double-linked list detected");
+    }
+
+    if (link == list)
+        list = list->next;
+
+    link->next = NULL;
+    link->prev = NULL;
+
+    return list;
+}
+
+/**
+ * g_list_delete_link:
+ * @list: a #GList, this must point to the top of the list
+ * @link_: node to delete from @list
+ *
+ * Removes the node link_ from the list and frees it. 
+ * Compare this to g_list_remove_link() which removes the node 
+ * without freeing it.
+ *
+ * Returns: the (possibly changed) start of the #GList
+ */
+GList *g_list_delete_link (GList *list, GList *link_)
+{
+    list = _g_list_remove_link (list, link_);
+    _g_list_free1 (link_);
+
+    return list;
+}
+
+/**
+ * g_list_insert_before:
+ * @list: a pointer to a #GList, this must point to the top of the list
+ * @sibling: the list element before which the new element 
+ *     is inserted or %NULL to insert at the end of the list
+ * @data: the data for the new element
+ *
+ * Inserts a new element into the list before the given position.
+ *
+ * Returns: the (possibly changed) start of the #GList
+ */
+GList *g_list_insert_before (GList *list, GList *sibling, gpointer data)
+{
+    if (list == NULL)
+    {
+        list = g_list_alloc ();
+        list->data = data;
+        g_return_val_if_fail (sibling == NULL, list);
+        return list;
+    }
+    else if (sibling != NULL)
+    {
+        GList *node;
+
+        node = _g_list_alloc ();
+        node->data = data;
+        node->prev = sibling->prev;
+        node->next = sibling;
+        sibling->prev = node;
+        if (node->prev != NULL)
+        {
+            node->prev->next = node;
+            return list;
+        }
+        else
+        {
+            g_return_val_if_fail (sibling == list, node);
+            return node;
+        }
+    }
+    else
+    {
+        GList *last;
+
+        for (last = list; last->next != NULL; last = last->next) {}
+
+        last->next = _g_list_alloc ();
+        last->next->data = data;
+        last->next->prev = last;
+        last->next->next = NULL;
+
+        return list;
+    }
+}
+