Write up how GemDB could reach Windows

[jgfoster]

Design notes only — no behaviour changes. docs/reaching-windows.md records the options for Windows support, what was measured versus assumed, and a recommended order of work.

Why it isn't the WSL-vs-Docker question it looks like

The obstacle isn't the extension: there is no GemStone server for Windows (measured — the catalog 404s for both Windows_NT keys at 3.7.5). So every option puts the database on Linux and differs only in where the seam falls.

Split by frequency, that seam is cheap:

• Data plane (every cell, keystroke, streamed print()) is already remote — gcits is RPC-only and logs in through NetLDI, so pointing at a stone in a VM or container is a login string, not an architecture.
• Management plane (install, create, start/stop, gslist) needs exactly one primitive: run a command in the Linux — wsl.exe -e or docker exec.

Design against that primitive and WSL and Docker become two thin backends of one interface, so the default on Windows can be chosen late, from measurements.

Two findings worth having written down

GemTalk publishes a Windows client kit even without a Windows server, and it contains libgcits-3.7.5-64.dll — the very library session.ts loads. Our vendored GCI layer already documents what that DLL lacks (non-blocking login, post-3.6.2 debug calls) and treats both as optional, and none of the GCI functions session.ts calls is in that absent set. So notebooks and the shell running natively on Windows against a Linux server is plausible. Known gap: gemdb file.py needs a linked gem, and the Windows topaz is RPC-only.

Jasper's WSL support measures ~9,000 lines across 20+ files — which reads as a warning until you notice most of it exists to manage many stones, versions and backups from the Windows side. That's precisely the surface GemDB deliberately doesn't have.

The Docker section is mostly about licensing

NOTICE says the engine is downloaded from GemTalk under GemTalk's terms and that this extension grants nothing. Baking the engine into a published image inverts that — we become the distributor, and a docker pull presents nobody a license. GemTalk owns GemStone so it's a decision you can make, but it should be a decision, not a side effect of writing a Dockerfile.

A thin image keeps the posture and still wins the prize, because the prize comes from the container rather than its contents: --shm-size and a container's irrelevant RemoveIPC mean both sudo prompts disappear — the two hardest moments in first run.

Registry recommendation is GHCR, and pull limits decide it: Docker Hub allows 100 anonymous pulls per 6 hours per IPv4 address or IPv6 /64 (measured), which an office behind one NAT shares, and the failure lands on a user's first run. GHCR also matches Grail's existing ci-base precedent, and our ubuntu-latest + ubuntu-24.04-arm runners build a multi-arch manifest natively.

Recommended order

1. WSL window first — VS Code's WSL extension runs the extension host inside WSL, so our published linux-x64 build already works there. Needs a smoke test and README text, no new code.
2. Prototype the Docker backend on macOS — derisks what every later option shares (RPC to a non-local NetLDI, the gem port range through published ports, forwarders across a real network boundary) and may graduate from scaffolding to a shipped mode.
3. Then consider the native Windows client, reusing the seam from step 2.

Everything needing hardware we don't have is collected under Unverified rather than asserted — including the one cheap experiment that would settle most of the Windows question (point a koffi script at the DLL, log in to a stone in WSL2, run one GciTsNbExecute/GciTsBreak cycle).

Packaging note

docs/** is added to .vscodeignore. Without it the new folder would have shipped in every .vsix; verified with vsce ls that docs/ contributes 0 files while README/CHANGELOG/LICENSE/NOTICE still ship.

🤖 Generated with Claude Code