TeslaRel410/emulator/XP-PORT-PLAN.md

# One archive, Windows XP -> Windows 11 (fleet-floor plan)

> **STATUS 2026-07-11: BACK-BURNERED (operator call).** This is the plan of
> record for when the port is picked up, not active work. Active effort stays
> on the modern archive's remaining details (DEPLOYMENT-PLAN OPEN items +
> the Phase 0 fleet answers below, which are cheap to gather meanwhile).

Fleet reality (operator, 2026-07-11): the surviving ~140 cockpits are
**overwhelmingly Windows XP**, a **few Windows 2000**, **4 original DOS PCs**
(Japan), and **Win10 migrations are only now starting**. The cockpit PCs are
**more modern and powerful than "runs XP" suggests** -- the OS floor is a
software constraint, not a hardware one. So the deployable archive must
install and run on **XP SP3 (32-bit) through Windows 11 (x64)** from the
**same zip** -- not an XP fork.

Current state (see `DEPLOYMENT-PLAN.md`): the packaged pod is INSTALL-VERIFIED
on modern Windows, but every shipped binary is x64 and the floor is effectively
Win10: pod-launch is .NET 8, renderer.exe is frozen Python 3.13 (moderngl,
GL 3.3), configure.ps1 needs the Win8+ NetAdapter cmdlets, and the capture
stack policy assumes Npcap (Win8.1+). None of it loads on XP.

## Scope decisions (settled unless marked OPEN)

- **Floor = XP SP3, 32-bit.** Every artifact *inside the zip* becomes 32-bit
  x86, PE subsystem 5.1, XP-safe API surface. 32-bit runs unchanged on
  Win10/11 under WoW64 -- that is the whole dual-target trick.
- **The 4 DOS cockpits are out of scope** -- they run BT/RP 4.10 natively on
  the original hardware; the emulation archive is irrelevant there.
- **Windows 2000 is OUT OF SCOPE (operator call, 2026-07-11).** The few 2000
  units either get lifted to XP SP3 or wait for their Win10 migration; the
  archive never targets 2000.
- **Dev-side tooling stays modern.** `package.ps1`, `freeze.ps1`, the build
  rigs -- none of it ships; only pod-side artifacts change.
- **The TeslaConsole/TeslaLauncher contract is unchanged** (zip + one folder +
  `postinstall.bat` elevated; console registers/invokes/kills). XP has no UAC,
  so "elevated" degrades gracefully to the admin account TeslaLauncher already
  runs under on the fleet.

## The five blockers -> five workstreams

| # | Component | Today | XP->11 plan |
|---|---|---|---|
| A | dosbox-x.exe | x64 MinGW64 static (v2026.06.02 + our patches) | 32-bit XP-compatible build of the same patched tree |
| B | pod-launch | .NET 8 win-x64 | native Win32 C++ supervisor, 32-bit, /SUBSYSTEM 5.01 |
| C | renderer.exe | PyInstaller Py3.13 + moderngl (GL 3.3) | native port of Dave's vrview (fixed-function GL) -- the crux |
| D | configure.ps1 / postinstall | PowerShell 3+ cmdlets | fold into the supervisor exe (`--configure`); batch stays batch |
| E | capture stack | Npcap (manual, Win8.1+) | WinPcap 4.1.3 on XP / Npcap on Win10+, same wpcap.dll API |

### A. DOSBox-X: 32-bit XP-compatible build of our patched tree

Upstream DOSBox-X has continuously shipped "Windows XP compatible" 32-bit
MinGW builds; our tree is `emulator/src` = upstream **v2026.06.02** plus our
self-contained patches (VPX device, pcap RX filter, `serial3=file`, etc.).

1. Verify v2026.06.02 still has the XP build recipe (their MinGW "lowend"
   configs / release channel). If upstream dropped it, find the last
   XP-supporting tag and forward-port our patches (they are small and
   peripheral -- device layer, pcap filter, serial -- not core-emulation
   surgery).
2. Reproduce their XP toolchain (pinned 32-bit MinGW, msvcrt-linked -- NOT
   today's MSYS2 MINGW64/UCRT) and build **static**, same as the current
   packaging rule: imports = Windows system DLLs + delay-load `wpcap.dll` only.
3. SDL choice follows upstream's XP builds (their in-tree SDL1 is the
   conservative default; SDL2-for-XP only if their recipe blesses it).
   `output=surface`/`ddraw` on XP -- do not assume a GL-capable desktop.
4. Re-verify on XP the features the pod depends on: VPX TCP frame stream
   (:8621), NE2000+pcap against WinPcap, AWE32/EMU8000 (bt/rp REQUIRE sound --
   the FAST SOS clock dies without it), `serial3=file` logging, window title /
   positioning hooks that `pod_deploy` relies on.

### B. Supervisor: native Win32 C++ (replaces .NET 8 pod-launch)

The design survives verbatim -- Job Object + `KILL_ON_JOB_CLOSE` exists since
Win2000, and `JobObject.cs`/`ChildProcess.cs`/`Focus.cs` are already thin
P/Invoke wrappers around the exact Win32 calls the C++ version will make
directly. Port, don't redesign: CreateJobObject/SetInformationJobObject/
AssignProcessToJobObject/CreateProcess suspended -> assign -> resume ->
WaitForSingleObject, plus the window-layout/focus pass.

- Build 32-bit, XP-targeting toolset (MSVC `v141_xp` or the same pinned MinGW
  as A), statically linked CRT -- **zero runtime deps** (rejecting .NET
  Framework 4.0: it would add an air-gapped framework install to every XP
  cockpit for no benefit).
- **XP has no nested job objects** (one job per process before Win8). OPEN
  (Phase 0 gate): does TeslaLauncher on the fleet already put children in a
  job? If yes: launch the supervisor `CREATE_BREAKAWAY_FROM_JOB` (needs
  launcher-side `JOB_OBJECT_LIMIT_BREAKAWAY_OK`) or fall back to a
  watchdog/kill-tree mode. If no (likely -- native titles are plain children):
  nothing changes.
- Drop `createdump.exe`-style diagnostics; a supervisor log file replaces it.

### C. Renderer: native vrview port -- the crux, and a decision with Dave

Python is a dead end on XP: CPython dropped XP at 3.5, Dave's GL backend needs
moderngl (GL 3.3 core -- no XP-era GPU/driver has it), and the numpy software
rasterizer (`vrview.Renderer`, today's fallback in `_backend.py`) is a
debugging reference, not something a P4 will push at mission rate.

**Plan of record: port vrview to C/C++ against fixed-function OpenGL
(1.1 floor, 1.4-1.5 typical on XP-era GeForce/Radeon).** The scene is
1995-vintage art (untextured/lightly-textured polys, flat/gouraud lighting,
the death-camera pass) -- it predates shaders; fixed-function multitexture
covers it. One binary then runs XP through Win11 (GL 1.x still works
everywhere), and the modern moderngl renderer becomes a dev-rig reference.

- The interface is already frozen and OS-agnostic: `renderer.exe tcp:8621
  <live.fifodump>` -- a TCP client consuming the VPX frame stream. The port
  swaps cleanly under pod-launch and package.ps1 with zero contract change.
- Spike first (with Dave): inventory what `vrview_gl` actually uses of GL 3.3
  and map each feature to fixed-function or CPU-side transform. Frame
  coalescing and SceneCache logic translate 1:1.
- Fallbacks, in order: (1) **two-artifact split** -- ship both renderers,
  dispatcher picks by OS (modern rigs keep the verified moderngl exe; XP gets
  the port) -- acceptable but two codebases; (2) software rasterizer in C
  (SSE2) if the GPU census says the XP boxes have no usable GL driver at all;
  (3) companion mini-PC driving the main view head over the existing TCP
  bridge -- architecturally free, but it changes cockpit wiring, so it is a
  per-site rescue, not the plan.

### D. Install tooling: one native exe configures, batch stays batch

`postinstall.bat` is already cmd-only and runs on anything NT -- keep it.
`configure.ps1` cannot run on XP (PowerShell 2.0 max, no NetAdapter module),
and VBScript is being removed from Win11, so scripting is the wrong home.

**Fold steps 2-4 into the supervisor: `pod-supervisor --configure -Root ...`.**
Same logic, Win32 APIs that exist on both ends: `GetAdaptersAddresses` (XP+)
for the physical-adapter/static-IPv4 scan (keep the fail-loud ambiguity rule
and `-BayIp`/`-ConsoleIp` overrides), the same letter-leading `realnic=` GUID
fragment, bayIP+100 derivation, `02:00:...` MAC, WATTCP.CFG stamping, and
`@@TOKEN@@` template rendering. postinstall calls the exe instead of
PowerShell. One compiled artifact then owns configure + launch + kill on every
OS, and the PowerShell dependency leaves the archive entirely.

Also: drop `vc_redist.x64.exe` handling (wrong arch for the fleet; statically
linked artifacts need no redist at all).

### E. Capture stack: WinPcap on XP, Npcap on Win10+, one dlopen surface

DOSBox-X talks to `wpcap.dll`, and WinPcap 4.1.3 and Npcap both provide it
(Npcap in WinPcap-compat mode). The manual-install-per-cockpit policy
(operator consensus 2026-07-10) already fits: it becomes **"install the
capture stack for your OS, once"** -- WinPcap 4.1.3 on XP, Npcap on Win10/11.

- WinPcap's BSD-style license permits redistribution, so the XP installer CAN
  be bundled in `deploy\` and auto-installed by postinstall (unlike Npcap,
  whose free license forbids bundling -- part of why the manual policy
  exists). postinstall detection becomes: `sc query npcap || sc query npf`.
- The co-located checksum-offload killer is Npcap/host-capture specific;
  real deployments (console on its own machine) are immune on any OS. If a
  co-located XP rig is ever needed, offload disable lives in the NIC's
  advanced properties instead of `Disable-NetAdapterChecksumOffload`.

## CPU headroom: verify, but likely a non-issue

BT/RP 4.10 targeted P90-PPro200; DOSBox-X's 32-bit dynamic core wants a
multi-GHz host to emulate that class of CPU *while also* running EMU8000
synthesis and feeding the VPX stream -- and the renderer competes for the same
cores. Per the operator (2026-07-11) the cockpit PCs are notably more powerful
than their XP installs suggest, so this is expected to pass; the Phase 1 bench
on a representative box stays as the cheap confirmation gate (Core2-class or
better = comfortable), not as a program risk.

## Phasing

- **Phase 0 -- census + contract checks (blocks everything).**
  Per-cockpit survey template: CPU/RAM, GPU + driver GL caps, video head
  count/wiring, NIC model, OS + SP, free disk. Fleet answers needed:
  TeslaLauncher job-object usage (B), which console build the venues run and
  where the `+100 DOSBox flag` lands (console workstream, unchanged from
  DEPLOYMENT-PLAN), Win2000 unit count (scope), representative XP loaner box
  for the bench.
- **Phase 1 -- DOSBox-X XP build + THE BENCH (biggest unknown first).**
  Workstream A; exit gate = egg->mission at FAST clock with sound on
  representative XP hardware, WinPcap mesh verified between two XP boxes.
- **Phase 2 -- supervisor + configure exe (B + D).** Exit gate = fresh zip
  extract -> postinstall -> configure -> launch -> kill-cascade on XP SP3 VM
  and Win11, same zip.
- **Phase 3 -- renderer port (C, with Dave).** Spike -> port -> live-verify
  against the frozen VPX stream on both OS ends.
- **Phase 4 -- packaging + validation matrix.** package.ps1 swaps in the
  32-bit artifact set (it already auto-bundles what's present). Matrix: XP SP3
  VM (bridged pcap), Win11 x64, then a real XP cockpit soak; renderer decay /
  death-camera / mission-review passes re-run per `CAMERA-REVIEW-NOTES.md`.

The current x64 package keeps shipping to Win10/11 rigs throughout; the XP
work replaces it only when the same zip passes the full matrix on both ends.

## OPEN items

1. Phase 0 census results -- GPU/driver GL caps decide the renderer fallback
   (CPU expected fine per operator; confirm with the bench).
2. TeslaLauncher job-object behavior on the fleet (breakaway or not).
3. Fleet console build + where the per-title DOSBox `+100` flag is applied.
4. Upstream v2026.06.02 XP-build recipe intact? (else: last XP-supporting tag
   + patch forward-port).
5. Renderer port ownership: likely **in-house** (operator, 2026-07-11 --
   "we may have to do the renderer work ourselves"); Dave's involvement
   reduces to the vrview_gl feature inventory / consultation. The native
   fixed-function port stays the plan of record either way -- vrview (the
   software reference) plus the frozen VPX stream give us a full spec and a
   pixel-comparison oracle without needing the original author.