Document t5de build and findings about the 554.8 client

Co-Authored-By: Claude Opus 5.5 <[email protected]>

CLAUDE.md

@@ -22,6 +22,22 @@ modern stack.
   deterministic, so unchanged commits re-export byte-identically.
 - The base must be identical on every machine: uncompyle6/xdis are pinned, output is normalized (`base.py`), and
   the base commit has a fixed author and date. For 554.8 the base commit is `7c544ab`.
+- `t5de build` builds work/'s HEAD into `build/IMVUClient/`. `splice27.py` (run under Python 2.7) compares base and
+  patched source per function and compiles only changed/added functions and methods (no `-O`: the decompiler shows
+  explicit `raise AssertionError` as `assert`). Each patched module's code runs the original module code object
+  unchanged, then the overrides; methods are compiled in a same-named class body (private names mangle right) and
+  copied onto the original class. Module- and class-level changes, removals, and decorators that use class-body
+  names are errors; import-time references to changed functions (aliases, `from M import f`, star imports) are
+  warnings. Replaced definitions stay reachable as `_t5de_original_<name>` (class attribute for methods, module
+  global for functions) so patches can wrap them. The build warns when a replaced definition's decompiled base
+  doesn't recompile to IMVU's bytecode (e.g. `Network.urlopen`), unless the patch calls its original. `build.py`
+  also repacks `library.zip` and the jar (original entry order and metadata; both are uncompressed), leaves out
+  `devicefingerprint.exe` and `npfpbase_vc10.dll`, rewrites the QualityAgent's crash report host to `127.0.0.1`,
+  creates `ui/profile` (empty in a real install, so 7-Zip skips it; the client crashes on startup without it),
+  and recomputes `checksum.txt`. Builds are byte-reproducible.
+- Reporting endpoints share hosts with the API (`client-dynamic`, `secure`, `www.imvu.com`), so they're blocked by
+  URL in `Network.urlopen`/`post_multipart` (patch 16), which logs each refusal as `t5de: blocked request to`.
+  Only `bugs.imvu.com` is reporting-only, so OS-level blocking (hosts/firewall) can't do much more.
 
 ## Verified facts (client 554.8)
 
@@ -32,17 +48,20 @@ modern stack.
 - Bytecode is Python 2.7 (magic 62211); 357 first-party modules. `imvu/tool/RadioTool.py` fails to decompile and
   is stubbed.
 - The decompiler is deterministic but not faithful: recompiling decompiled code gives identical bytecode for only
-  ~60% of modules, and 6 don't compile at all. So never ship whole recompiled files.
+  ~60% of modules, and 6 don't compile at all. So never ship whole recompiled files. The 6 (mostly mangled string
+  escapes): `imvu/bugreport/__init__.py`, `imvu/geography.py`, `imvu/translation.py`, `imvu/task/util.py`,
+  `imvu/platform/windows.py` (null bytes), `main/login.py`. Patches avoid them.
+- `IMVUQualityAgent.exe` launches and restarts the client, and on a crash it sends
+  `GET /catalog/imvu_monitor_submit.php?cid=` to `www.imvu.com` itself (raw WSOCK32), out of reach of Python patches.
+- `npfpbase_vc10.dll` is a BlueCava device-fingerprinting browser plugin that the embedded Gecko can load.
+- Patch 1 also filters Creator Mode facts; patch 14 drops all facts. The filter is kept so patch 1 stands alone.
 - `imvu.expectModules` (called from the exe's boot script) rejects unexpected modules loaded at startup;
   `--no-expected-module-check` bypasses it.
 - The UI is XULRunner/Gecko; IMVU's own JS in the jar isn't minified.
 
-## Next: `t5de build`
+## Next
 
-Function-level splicing: compare base vs patched decompiled Python per function (parsed with a Python 2.7 helper),
-compile only changed/added functions, and wrap the original bytecode: a new module executes the original code
-object, then applies overrides (a `@patch_class(Target)` decorator over a same-named class gets private-name
-mangling right). Module-level changes are errors unless a file opts into whole-file mode. Warn about references
-bound at import time (e.g. handler dicts), which keep pointing at the original function. Also repack the jar
-deterministically and recompute `checksum.txt`. Port `AccountPatch` (Python) and `ChatRoomSearchPatch` (UI) from
-the old repo as the first real patches.
+- The build runs on a real client (launched directly, without `IMVUQualityAgent.exe`): login and a session work,
+  with no reporting requests sent. Each patch's feature still needs checking in the client.
+- `t5de install` to `%LOCALAPPDATA%\T5DEClient` (keep the exe named `IMVUClient.exe`: `imvu/program/windows.py`
+  finds the agent by replacing that name). User data is `%APPDATA%\T5DE`, settings `HKCU\Software\T5DE` (patch 15).

README.md

@@ -5,7 +5,9 @@ itself is downloaded from IMVU and decompiled locally, and never committed.
 
 ## Setup
 
-Needs Python 3.12+, git, and 7-Zip (`7z` on PATH, or installed in its default location on Windows).
+Needs Python 3.12+, git, and 7-Zip (`7z` on PATH, or installed in its default location on Windows). `t5de build`
+also needs Python 2.7, the client's own Python: found through the `py` launcher on Windows, `python2.7` or `python2`
+on PATH, or the `T5DE_PYTHON27` environment variable.
 
 ```sh
 python -m venv .venv
@@ -34,3 +36,22 @@ the files in `patches/` to this repository.
 
 `t5de setup --force` rebuilds `work/` from scratch; run `t5de save` first, or local commits are lost.
 
+Python patches can change or add functions and methods, but not module-level or class-level code: only the
+functions a patch touches are recompiled, because recompiling whole decompiled modules isn't reliable. The original
+of every replaced definition stays callable as `_t5de_original_<name>` (`self._t5de_original_<name>` for methods),
+so a patch can wrap IMVU's code instead of rewriting it. `t5de build` warns when a patched function's decompiled
+original doesn't recompile to IMVU's bytecode; wrap those rather than editing the decompiled text.
+
+## Building
+
+```sh
+t5de build
+```
+
+Builds a patched client from the commits in `work/` into `build/IMVUClient/`. Run `build/IMVUClient/IMVUClient.exe`
+to test it, with a throwaway IMVU account. The patched client keeps its settings and logs apart from an installed
+original client (`HKCU\Software\T5DE` and `%APPDATA%\T5DE`), so both can be used side by side.
+
+Every request to IMVU's reporting endpoints that the patched client refuses is logged as
+`t5de: blocked request to` in `%APPDATA%\T5DE\IMVULog.log`.
+