Finish steam

docs/reverse-engineering/executable-parity-2026-07-05/README.md

@@ -0,0 +1,38 @@
+# Executable Parity Gap Driver - 2026-07-05
+
+This folder turns the remaining `quakelive_steam.exe` parity work into two machine-readable ledgers plus a focused implementation plan.
+
+## Files
+
+- `executable-symbol-resolution-gaps.csv`: every retail executable Ghidra function that is either unaliased or currently treated as a low-confidence alias.
+- `executable-function-size-disparities.csv`: every retail executable Ghidra function whose size cannot be matched exactly against the freshly built source `Release|Win32` map, or whose source symbol is missing.
+- `executable-parity-implementation-plan.md`: prioritized work plan for closing executable parity gaps.
+- `summary.json`: counts used by this index.
+
+## Current Counts
+
+| Measure | Count |
+| --- | ---: |
+| Retail executable Ghidra functions (`functions.csv`) | 5473 |
+| Functions with a current executable alias | 3510 |
+| Functions without a current executable alias | 1963 |
+| Symbol-gap CSV rows | 3681 |
+| Source Release map function symbols parsed | 7070 |
+| Size-disparity CSV rows | 5451 |
+| Exact size matches omitted from size CSV | 22 |
+
+## Method Notes
+
+The symbol-gap CSV intentionally separates observed facts from inference. `alias_key` and `current_alias` come from `references/analysis/quakelive_symbol_aliases.json`; module and external-library fields are heuristic labels based on alias prefixes, nearby aliased functions, imports, current source-map objects, and known engine ownership bands. Rows marked `suspected_external_dependency=yes` should usually be resolved as dependency provenance or replacement-policy work before being treated as engine source work.
+
+The size-disparity CSV was generated after a successful compatibility build:
+
+```powershell
+& 'C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe' src\code\quakelive_steam.vcxproj /p:Configuration=Release /p:Platform=Win32 /p:PlatformToolset=v141 /m
+```
+
+That produced `build/win32/Release/bin/quakelive_steam.map`, which was parsed for source-side function symbol sizes. This is useful for triage, but it is not a strict retail compiler match: retail evidence points at VC++ 2010 SP1-style `v100`, while this run used the repo-supported `v141` compatibility override and source online services remained default-disabled.
+
+## Reading The CSVs
+
+For `executable-symbol-resolution-gaps.csv`, start with `resolution_bucket=unaliased` and high-byte-size rows, then move to low-confidence third-party/generated aliases. For `executable-function-size-disparities.csv`, prioritize rows where `comparison_status=source_symbol_missing_in_release_map` and `suspected_external_dependency=no`; then inspect `severity=high` size mismatches in client, server, qcommon, renderer, and platform modules.

docs/reverse-engineering/executable-parity-2026-07-05/executable-parity-implementation-plan.md

@@ -0,0 +1,108 @@
+# Executable Parity Implementation Plan
+
+Generated: 2026-07-05
+
+## Scope
+
+This plan targets the remaining parity gap in the retail host executable, `quakelive_steam.exe`. It is broader than the existing Steamworks note: it covers host client/server/qcommon/renderer/platform behavior, statically linked codecs, generated C++/CRT helpers, and source-vs-retail size drift.
+
+Primary evidence:
+
+- `references/reverse-engineering/ghidra/quakelive_steam/functions.csv`
+- `references/reverse-engineering/ghidra/quakelive_steam/analysis_symbols.txt`
+- `references/hlil/quakelive/quakelive_steam.exe/`
+- `references/analysis/quakelive_symbol_aliases.json`
+- `src2/ghidra/quakelive_steam/`
+- `build/win32/Release/bin/quakelive_steam.map` from the 2026-07-05 `v141` compatibility build
+
+## Baseline
+
+- Retail Ghidra function rows: 5473.
+- Function rows with current executable aliases: 3510.
+- Function rows with no current executable alias: 1963.
+- Symbol-gap rows after adding low-confidence dependency/generated aliases: 3681.
+- Size-disparity rows against the current Release map: 5451.
+- Exact source-size matches omitted from the disparity ledger: 22.
+
+Estimated executable parity before this documentation pass: **65% symbol-address coverage / 45% strict source-shape parity**.
+Estimated executable parity after this documentation pass: **65% symbol-address coverage / 45% strict source-shape parity**.
+
+The percentages do not move because this task creates tracking evidence rather than reconstructing source behavior.
+
+## Phase 1 - Make The Host Map Authoritative
+
+1. Convert `executable-symbol-resolution-gaps.csv` into the host executable work queue.
+2. Add a real `references/symbol-maps/quakelive_steam.json` or equivalent generated ledger with per-address status, mirroring the DLL maps.
+3. Normalize duplicate address keys (`FUN_004...`, `sub_4...`, uppercase/lowercase) into one canonical function row per address.
+4. Add CI or pytest coverage that proves the executable alias ledger still maps every promoted function address and fails on reintroduced `UNRESOLVED_*` placeholders.
+
+Exit criteria:
+
+- Every `functions.csv` row has either a promoted alias, a documented external-dependency owner, or a deliberate compiler/runtime classification.
+- The executable has a machine-readable coverage header like `cgame.json` and `ui.json`.
+
+## Phase 2 - Resolve Unaliased Engine Rows First
+
+1. Sort `executable-symbol-resolution-gaps.csv` by `resolution_bucket=unaliased`, `suspected_external_dependency=no/maybe`, and descending `retail_size_bytes`.
+2. For each target, start from `functions.csv`, then cross-check HLIL control flow, strings, imports, and caller/callee context.
+3. Prefer source-owned names that already exist under `src/code/client`, `src/code/server`, `src/code/qcommon`, `src/code/renderer`, `src/code/win32`, and `src/code/botlib`.
+4. Keep evidence notes short and factual: observed facts, inferred meaning, confidence, open questions.
+
+Exit criteria:
+
+- Large unaliased host-owned functions are exhausted before low-value tiny thunks.
+- New aliases are backed by at least two evidence signals whenever possible.
+
+## Phase 3 - Quarantine External Dependencies
+
+1. Treat `ZeroMQ/CZMQ`, `libpng`, `zlib`, `libjpeg`, `Ogg/Vorbis`, FreeType, MSVC STL, and CRT rows as dependency provenance work unless they bridge directly into engine behavior.
+2. Decide per dependency whether the parity target is exact static source reconstruction, documented replacement, or runtime-external boundary.
+3. Keep online-service dependencies behind `QL_BUILD_ONLINE_SERVICES`; do not move ZMQ, Steamworks, Awesomium, advert, or live WebUI behavior into default builds.
+4. For codec stacks, document whether retail statically linked code, repo-managed static libs, or current source wrappers are the intended parity lane.
+
+Exit criteria:
+
+- External rows no longer obscure engine gap counts.
+- Dependency replacement policy is explicit for each library cluster.
+
+## Phase 4 - Close Source Missing Symbols
+
+1. Use `executable-function-size-disparities.csv` rows with `comparison_status=source_symbol_missing_in_release_map` and `suspected_external_dependency=no` as implementation candidates.
+2. Distinguish true missing functions from optimized-away statics, inline-only helpers, renamed source functions, default-disabled online-service owners, and external dependency omissions.
+3. Add source only when the behavior belongs to the open reconstruction. For Quake Live-only online services, prefer stubs/fallbacks behind `QL_BUILD_ONLINE_SERVICES`.
+4. Rebuild Release and regenerate the size-disparity ledger after each batch.
+
+Exit criteria:
+
+- Host-owned source-missing rows are explained or implemented.
+- Default-disabled online-service boundaries are visible in the CSV notes or plan updates.
+
+## Phase 5 - Use Size Drift As A Triage Signal
+
+1. Treat `severity=high` size mismatches as review candidates, not automatic bugs.
+2. Confirm with HLIL before changing source: compiler version, optimization, inlining, and debug metadata can all alter sizes.
+3. Prefer mismatches where source and retail names align, the module owner is host-owned, and the delta is not explained by `v141` vs retail `v100` codegen.
+4. When a mismatch drives a source change, add or update a focused parity test that checks behavior, not byte size alone.
+
+Exit criteria:
+
+- Size mismatch rows are either explained by toolchain/dependency policy or paired with source parity tasks.
+- A future `v100` map can replace the `v141` baseline without changing the CSV schema.
+
+## Phase 6 - Regenerate And Track
+
+Regenerate this package whenever executable aliases or host source owners materially change:
+
+1. Build `Release|Win32` with the best available parity toolset.
+2. Parse `build/win32/Release/bin/quakelive_steam.map`.
+3. Regenerate both CSVs.
+4. Update counts in this plan and `README.md`.
+5. Tick completed implementation tasks into `IMPLEMENTATION_PLAN.md` only after behavior or evidence actually lands.
+
+## Immediate Priority Order
+
+1. Large unaliased functions in client/qcommon/server/renderer bands.
+2. Host-owned source-missing aliases in the size-disparity CSV.
+3. High-severity size mismatches for non-external modules.
+4. ZMQ/libpng/zlib/libjpeg/Ogg dependency clusters, grouped as provenance or replacement-policy work.
+5. Compiler/runtime generated helpers, only after they block real engine ownership claims.