Files
aevolution/docs/adr/0086-windows-client-package.md
T
dingoandClaude Opus 5.5 1819ebc0ab
Foundation / checks (checks) (push) Successful in 32m47s
Foundation / checks (client) (push) Failing after 10m1s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m53s
Foundation / checks (network) (push) Successful in 11m18s
Foundation / checks (postgres) (push) Successful in 40m20s
Foundation / checks (tsan) (push) Successful in 7m46s
Foundation / postgres-tools (push) Skipped
Foundation / image (push) Skipped
Foundation / server-image (push) Skipped
Switch the engineering client to M10 sessions (M10.5c)
evo-client's remote mode now runs over RegionSessionClient (QUIC, session
v2): snapshot-fed environment and organism views, the camera following the
server's view until the user moves it and then driving the interest, intention
records with a simulated state, and reconnects with the next grant of a bundle.
The launcher reads 160-byte M10 grants and defaults to the dev route.

- quic::resolve_ipv4 shared by the client and evo-session-probe
- evo-session-probe grants: owner-only bundles of 1-64 grants
- evo-server --m10-max-grant-lifetime (dev only, 60..3600 s)
- presets client-network/client-package build QUIC; msquic links the CRT
  fully static; msquic.dll and msquic/OpenSSL licences in the Windows package
- client-remote-session test against a loopback region
- ADR-0093/0091/0086 amendments, M10_CLIENT_SESSIONS guide, validation

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-06 11:57:07 -04:00

67 lines
4.2 KiB
Markdown

# ADR-0086: Windows client package
## Status
Accepted for M9.8e (2026-10-02). Local packaging on the Windows development host;
Gitea Actions publication waits for a Windows runner. Internal test builds only.
## Context
Testers need a Windows x64 ZIP of the engineering client that runs on a clean
machine, says exactly which build it is, carries third-party notices, and cannot
leak development credentials. No Windows CI runner exists yet; the Linux runner
must not silently build Windows packages and no untested cross-compile is assumed.
## Decision
- Preset `client-package` (client + network) links the **static MSVC runtime**
(`CMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded`) for the client, SDL, Mbed TLS and
Dear ImGui, so no Visual C++ redistributable or Microsoft runtime DLL is shipped
or required. Executables may import only listed Windows system DLLs and the
bundled `SDL3.dll`; the scripts check this from the PE import tables.
- `EVO_REPRODUCIBLE` adds `/Brepro` to every MSVC compile and link, before any
dependency is added. ZIP entries are sorted, under one top folder, stamped with
the commit time. A rebuild of the same commit on the same toolchain should give
the same ZIP; this is verified, not assumed (see VALIDATION.md).
- Identity `g<12 hex of commit>[-dirty]` is configured as `EVO_BUILD_IDENTITY`
and printed by `evo-client --version`. Packaging refuses uncommitted tracked
changes unless `-AllowDirty`, which marks the identity dirty.
- `tools/client/package-windows.ps1` builds and runs the client/network CTest
suite in that preset, then stages an explicit allowlist: `evo-client.exe`,
`SDL3.dll`, README, BUILD-INFO (commit, toolchain, dependency versions and
source checksums, test summary), THIRD-PARTY-NOTICES and LICENSES copied from the
checksum-verified sources (SDL with its compiled HIDAPI, yuv2rgb, stb_image and
Khronos headers; Mbed TLS under Apache-2.0; Dear ImGui with embedded fonts and
stb headers), and SHA256SUMS. It refuses any other file, credential file types,
PEM private keys or certificates, and embedded user-profile paths.
- `tools/client/verify-windows-package.ps1` needs no Visual Studio: it checks the
ZIP digest, content and checksums, imports and secrets, then runs the extracted
client with only system directories on PATH (version, usage error, fixture and
launcher with the dummy driver, credential-file failure; optionally a window).
- The README states an internal engineering test build: no licence is granted and
it must not be redistributed. Third-party licences are reproduced in full.
- Publication: none automated yet. The ZIP and `.sha256` are produced locally; a
Gitea Actions job will be added only with a registered Windows runner.
## Alternatives considered
- App-local VC++ runtime DLLs: redistributes Microsoft binaries and their terms.
- Requiring the VC++ redistributable: a setup step that testers can miss.
- CPack: adds a generator layer for a single ZIP with custom checks.
- A gated Windows workflow job now: unexecuted and untested until a runner exists.
## Consequences
Static runtime: each image has its own CRT state; SDL's C API passes no CRT objects
across the DLL boundary. Package and verification scripts change with the file
list. Clean-machine/VM runs and minimum hardware remain M9.8g qualification.
The notice inventory is an engineering record, not a legal review.
## Amendment (M10.5c, 2026-10-06): msquic.dll
- The package adds `msquic.dll` (msquic 2.6.2, MIT, with OpenSSL 3.5.9 built static inside,
Apache-2.0; pins and sources as in ADR-0090) and `LICENSES/msquic.txt` and
`LICENSES/OpenSSL.txt`, copied from the verified sources. BUILD-INFO lists both pins.
- msquic links the whole C runtime statically (`QUIC_STATIC_LINK_PARTIAL_CRT=OFF`; its
default imported the UCRT forwarders). Allowed imports add `msquic.dll` and the system
DLLs it needs: `crypt32`, `iphlpapi`, `ncrypt`, `ntdll`. All three images are checked.
- Determinism: OpenSSL is built by msquic with nmake, outside CMake's `/Brepro`; the package
script sets `CL=/Brepro` (cl.exe reads options from it) and `SOURCE_DATE_EPOCH` (the
commit time, used by OpenSSL's build-date string) for the build.
- The package CTest run adds the label `quic-session` (QUIC session and client remote
session tests).