# M0 — shim bootstrap (proxy `binkw32.dll` + one hook)

**Result (2026-09-07): proven end to end on the real game.** The proxy DLL loads, forwards all
Bink calls, relocates the target RVA against the ASLR'd exe base, hooks `Mars::Application::Initialize`,
logs the call, and the game plays its intro and reaches the main menu.

## What was built
- `src/shim/binkw32.def` — 66 forwarders (`_BinkOpen@8 = binkw32_real._BinkOpen@8 @41` style),
  names and ordinals mirrored from the real DLL. Note: the real DLL has **66** exports including
  `_RADTimerRead@0`, which earlier lists missed. The exe imports 12 of them **by name** (no ordinals).
- `src/shim/main.cpp` — `DllMain` → `Shim_Init`: opens `<dll dir>\shim.log`, logs banner (build id,
  exe path, exe base + ASLR delta, provenance line lifted from `sots_addresses.h`), reads
  `shim.cfg` (`hooks=trace|off`), `MH_Initialize`, one MinHook hook on
  `exeBase + sots::addr::Mars_Application_Initialize`, `MH_EnableHook`. Detach → `MH_Uninitialize`.
- `third_party/minhook/` — MinHook vendored (BSD-2, see `VENDOR.txt` for commit).
- `CMakeLists.txt`, `cmake/toolchain-mingw-i686.cmake`, `CMakePresets.json` (`shim` = i686 MinGW
  cross, `host` = Linux placeholder test `tests/addr_smoke.cpp`).
- `tools/build-shim.sh` (build box), `tools/sync-build.sh` (dev box → build box), `tools/deploy.ps1`,
  `tools/undeploy.ps1` (game VM).

## Build & deploy
```
# dev box: push the tree to spicy:/bulk-storage/re-lab/build/sots-engine (== CT111 /srv/re-lab/...)
# and run tools/build-shim.sh inside CT111 (needs g++-mingw-w64-i686 binutils-mingw-w64-i686 cmake ninja-build)
tools/sync-build.sh
#   -> builds build-shim/binkw32.dll, diffs its export-name table against the real DLL (fails on mismatch),
#      stages binkw32.dll + shim.cfg + deploy.ps1 + undeploy.ps1 + BUILD_ID in /srv/re-lab/shim/dist (= Z:\shim\dist)

# game VM (re@192.168.10.139): Z: is per-logon, so pass share creds (or set RELAB_USER/RELAB_PASS)
powershell -ExecutionPolicy Bypass -File deploy.ps1 -ShareUser re -SharePass <pw>
#   stops the game, keeps the original as C:\SOTS\binkw32_real.dll (only if not already a proxy),
#   copies the proxy, writes shim.cfg only if absent, relaunches via scheduled task SOTS
powershell -ExecutionPolicy Bypass -File undeploy.ps1     # put the original back
```
Logs: `C:\SOTS\shim.log` (append mode, one banner per run). Screenshots: `qm monitor 140` screendump.

## Evidence (`/bulk-storage/re-lab/shim/logs/`)
- `m0.log` — the shim log. Key lines from the passing run (build `4a15301-20260907T2118Z`):
  ```
  ==== sots-engine shim (binkw32 proxy) build 4a15301-20260907T2118Z ====
  exe base=0x00e80000 (link-time image base 0x00400000, ASLR delta +11010048) pid=3808 shim=730c0000
  addresses: Source: sots-re ghidra/addresses.json @ daea98f, generated 2026-09-07 by tools/gen_addresses.py
  hook: Mars_Application_Initialize rva=0x004a0e50 -> va=01320e50
  hook: MH_Initialize -> MH_OK / MH_CreateHook -> MH_OK (trampoline=00e50fe0) / MH_EnableHook -> MH_OK
  Application::Initialize called (this=035c8128)
  ```
- `m0-main-menu.png` — main menu with the hook live (intro skipped with 3× Esc, ~35 s after launch).
- Export table: `build-shim/exports.txt`; `tools/build-shim.sh` printed
  `exports: 66 names, identical to binkw32.dll`.
- `hooks=off` run (first banner in `m0.log`, pid 6396): forwarders alone play the Bink intro — proxy proven
  separately from hooking.
- `tools/clean_room_check.sh` → OK.

## Gotchas
1. **Do not call the original from a C++ `thiscall` detour.** v1 did exactly that
   (`void __thiscall Detour(void* self) { log; orig(self); }`) and the game died inside Initialize with
   "Mars: Application error encountered" (`m0-crash-hookv1.{log,png}`). The prototype in
   `sots_addresses.h` is `[unverified]`; if Initialize takes stack args, returns via EAX or relies on
   EDX (fastcall-like), a calling wrapper corrupts the stack/registers on return. The shipped detour is
   an asm stub: `pushfl/pushal`, call a C logger with ECX, `popal/popfl`, **`jmp` to the trampoline**.
   It's correct for any convention but cannot log the return. Until a prototype is verified, use this
   pattern for every trace hook; only replace-hooks (that never call the original) may be plain C++.
2. Hooking from `DllMain` worked (process is single-threaded at that point; MinHook only touches
   kernel32). The fallback (install from the first forwarded Bink call) was not needed.
3. `--kill-at` / `--enable-stdcall-fixup` must NOT be passed to ld — they would strip the `@N`
   suffixes the exe imports by name. With a plain `.def` MinGW exports the names verbatim.
4. `objdump -p` lists `+base[` rows in both the address table and the name table; compare the
   `[Ordinal/Name Pointer] Table` section only (forwarder rows print `Forwarder RVA -- target`).
5. rsync `--exclude 'build-*'` also matches `build-shim.sh`; use `/build-*/`.
6. The CT is unprivileged: files written on the host must be `--chown=100000:100000` or the CT can't
   write its build dir. `Z:` mappings are per logon on the VM; SSH sessions start without it.
7. `shim.log` is held open by the running game; move/rotate it only after `Stop-Process`.