windows: fix native MSVC/Vulkan build portability

[ElderOrb]

This PR makes the native Windows MSVC + Vulkan build path link and test cleanly enough to use the existing Windows CI lanes.

What changed:

• add a small cross-platform compatibility layer for POSIX-only file, env, pid, mmap, and aligned-allocation helpers
• switch Windows-facing codepaths and tests to those helpers instead of relying on POSIX APIs directly
• fix the Windows shared-library packaging/link path, including /WHOLEARCHIVE handling and explicit blake3_vendored linkage
• make the Vulkan loader and shared-library tests work on Windows without Unix-only dlopen assumptions
• keep MSVC warnings visible but stop promoting unrelated native-Windows warning cleanup into a hard build blocker
• gate or adapt tests whose harnesses are currently POSIX-only

Why:

• the upstream tree already has Windows CI lanes, but the native MSVC/Vulkan path still had several portability and packaging blockers
• this change is intended to make that path buildable and testable in GitHub Actions without changing the Linux behavior

Validation:

• the branch was validated on a native Windows Strix Halo host
• GitHub Actions should exercise the existing Windows jobs for this PR

[localai-org-maint-bot]

This portability PR is not reviewable as a merge candidate while its own portability and build gates are red. The current head fails windows-msvc-cpu, windows-msvc-vulkan, both Linux build-test jobs, Vulkan verification, both sanitizer jobs, commit-protocol-tag, agent-record, device-leakage, and documentation-checkpoint. Please rebase onto current main, add the required FOLLOWING_AGENTS_PROTOCOL trailer to every PR commit, and push a head where the intended MSVC/Vulkan fixes pass their target jobs. After that, the large mechanical compatibility diff can be reviewed against a meaningful green signal.

[localai-bot]

Thanks for tackling this, and welcome — the Windows arm being red on every PR is a real problem and the centralising instinct here is the right one. Four hand-rolled setenv shims scattered across the tree is a genuine smell and a shared platform_compat.h is where that should end up.

I have to be straight with you though: as it stands this PR does not turn the Windows jobs green, and it breaks the Linux build in two places. Details below so you can judge what to keep.

The Windows jobs go redder, not greener

Both die in scripts/check-windows-portability.py before the compiler ever runs. Conclusions read from the API, head 45550dc:

windows-msvc-cpu     conclusion=failure  (job 94566363611)
windows-msvc-vulkan  conclusion=failure  (job 94566363526)

ERROR: include/vllm/support/platform_compat.h:17: unguarded POSIX include/call reaches Windows
ERROR: include/vllm/support/platform_compat.h:21: unguarded POSIX include/call reaches Windows
ERROR: src/vllm/multimodal/video_engine.cpp:21/59/64: unguarded POSIX include/call reaches Windows
ERROR: cpu_matmul_elem.cpp: F16C must be isolated in a dedicated translation unit

The current baseline red is three errors, all video_engine.cpp (issue #664, already fixed by open PR #677). This PR leaves those three and adds three of its own.

The two new ones are your #include <fcntl.h> and #include <sys/stat.h> at platform_compat.h:17,21 — which sit inside #if defined(_WIN32) and are legitimate MSVC CRT headers. So the checker is arguably over-broad here (its pattern matches the spelling regardless of branch). That's a fair thing to argue for changing, but changing a checker's semantics needs a spec plus red-before/green-after evidence under AGENTS.md, and this PR neither changes the checker nor makes the case.

Important, and not your fault: the reason your native Windows validation passed while CI fails is that your host build never runs this gate. And separately — even a perfect version of this PR could not have turned windows-msvc-cpu green, because #584 (test_openai_api_server crashing with STATUS_STACK_BUFFER_OVERRUN 0xC0000409) is still open and independent of everything here.

Two Linux breaks, both reproduced locally

1. -Werror=unused-function. vulkan_loader.cpp adds three helpers to an anonymous namespace and calls one:

$ g++ -std=c++20 -Wall -Wextra -Werror ... -c src/vt/vulkan/vulkan_loader.cpp
error: 'void ...CloseSharedLibrary(void*)' defined but not used
error: 'void* ...LoadSharedSymbol(void*, const char*)' defined but not used
# same command on base: compiles clean

2. Missing include. tests/vllm/v1/test_kv_offload_tiering.cpp:43 calls vllm::support::CurrentProcessId() but never includes platform_compat.h → 'vllm::support' has not been declared. This one is instructive: your /FI force-include in tests/CMakeLists.txt is MSVC-only, so it silently supplies the header to every test on Windows and to none on Linux. That's why it built for you. I swept the whole tree for the same class and this is the only instance — contained.

Three hunks I'd drop

• cmake/CompilerWarnings.cmake: /WX → /WX- plus COMPILE_WARNING_AS_ERROR OFF and blanket /wd4324 /wd4458. AGENTS.md is explicit that you may not turn a red gate green by widening a scope. Worth knowing: check-windows-portability.py:1710 tests "/WX" in warnings, and "/WX" in "/WX-" is True — so the gate is blind to its own inversion. The only bare /WX left in your version is on COMPILE_LANGUAGE:OBJCXX, i.e. Metal, which never builds under MSVC. That checker gap is ours and I'm filing it regardless of what happens here.
• VT_CPU_F16C_TARGET is defined and used nowhere (git grep returns only its own two definition lines) and it trips the F16C-isolation contract. Pure cost.
• nvfp4_persistent_cache.cpp — this file is if(NOT WIN32) at CMakeLists.txt:1352 and is hard-coded as WINDOWS_EXCLUDED_SOURCE in the checker, so it never compiles on Windows at all. The rewrite replaces ::mkstemp (random name, O_EXCL) with a predictable .tmp.<pid>.<counter> opened trunc, and drops ::fsync — flush() only drains the C++ stream buffer, so the write-then-rename durability guarantee is gone. The project's contract for exactly this operation lives one directory over in fs_io.cpp (CREATE_NEW, FlushFileBuffers, ::fsync, MOVEFILE_WRITE_THROUGH). Linux/CUDA regression for no Windows benefit.

Also inert: the elseif(MSVC) at CMakeLists.txt:1228 is unreachable — if(MSVC) at 1224 already matched — so the /WHOLEARCHIVE fix the body describes can't execute.

What I'd keep

The ARCHIVE_OUTPUT_NAME / blake3_vendored link fixes look like real repairs (I can't verify them from Linux). #undef CreateEvent correctly identifies the Win32 A/W macro collision, though the tree's idiom is #pragma push_macro/pop_macro rather than a bare #undef in a public header, which permanently unmaps the name for every downstream TU. And the shared-helper direction is right.

Sequencing

There are four other Windows PRs in flight and this collides with them. #524 hard-conflicts — you both edit tests/CMakeLists.txt and insert at the top of test_api_server.cpp, and #524 duplicates your M_PI and POSIX-stat work by other means. #578 is a third spelling of the same setenv shim. #677 fixes the three video_engine.cpp errors that are the actual current baseline red, so it's the shortest path to green and worth landing first.

My suggestion: let #677 and #584 land, then bring this back split into (a) the shared platform_compat.h with the two Linux breaks fixed and the /FI made cross-platform, and (b) the packaging/link fixes — dropping the /WX- downgrade, the dead F16C macro, the dead elseif, and the nvfp4 rewrite. That version is genuinely valuable and much easier to review.

One housekeeping note, and a normal thing for a first contribution: commits need a bare FOLLOWING_AGENTS_PROTOCOL line plus Following-Agents-Protocol: true, AI-Assisted: true and Assisted-by: trailers — that's what commit-protocol-tag and agent-record are flagging. See AGENTS.md § "Landing work". A tracking issue linked in the PR body is wanted too; ENG-RELEASE-WINDOWS is the row this belongs to.

[localai-bot]

Re-reviewed against current main, and the substantive work is now sound — thank you for turning it round. I verified by building rather than reading:

• /WX- and COMPILE_WARNING_AS_ERROR OFF are gone.
• Both Linux breaks are fixed. vulkan_loader.cpp compiles clean under -Wall -Wextra -Werror (the unused-function error is gone — CloseSharedLibrary is now actually called), and test_kv_offload_tiering.cpp no longer errors on vllm::support.
• The nvfp4_persistent_cache.cpp rewrite is dropped, and ::fsync is back — the write-then-rename durability guarantee is intact.
• Rebased onto current main, scripts/check-windows-portability.py reports Windows portability contract OK, under the stricter checker that landed in fix(GATE-WINDOWS-WARNING-POLICY): /WX- is not /WX, and OBJCXX is not the C++ compile (#774) #795.

Two things are left, and they are packaging rather than code.

1. platform_compat.h needs to live under src/, not include/

check-doc-checkpoint classifies any include/vllm/ edit as landing_page, user_usage and demands a docs/USAGE.md entry:

ERROR: commit 74ba3823f: changed feature_surface, landing_page, user_usage
       but did not update docs/FEATURES.md, docs/USAGE.md
ERROR: commit 15aa963a6: changed landing_page, user_usage
       but did not update docs/USAGE.md

There is nothing user-facing to say about it — it is a loader/test portability shim, not public ABI — so the right answer is to move it out of the public header tree rather than invent a USAGE entry. That is the same conclusion another change reached independently this week (#815 put voxtral_loader_internal.h under src/ for exactly this reason), and the house has the precedent already: qwen3_5_internal.h, voxtral_loader_internal.h, capi/engine_handle.h.

I tried to do this for you and stopped, because it is bigger than it looks. CMakeLists.txt:1283 is target_include_directories(vllm PRIVATE src) — PRIVATE, so src does not propagate to test targets. Ten of the eighteen includers are tests:

tests/capi/test_capi.cpp                    tests/parity/test_op_parity.cpp
tests/vllm/gguf_builder.h                   tests/vllm/test_qwen36_weights.cpp
tests/vllm/test_safetensors.cpp             tests/vllm/v1/test_kv_offload_connector.cpp
tests/vllm/v1/test_kv_offload_tiering.cpp   tests/vllm/models/test_minimax_h3_video_fold.cpp
tests/vt/test_nvfp4_persistent_cache.cpp
tests/vllm/model_executor/layers/attention/test_mla_attention_block.cpp

so each needs target_include_directories(<t> PRIVATE ${CMAKE_SOURCE_DIR}/src), which is the established per-target idiom (tests/CMakeLists.txt:1158 does exactly that for test_capi). I did not want to reshape ~60 files of your PR on your behalf without asking.

2. Commit trailers

74ba3823f8e6: [trailers] FOLLOWING_AGENTS_PROTOCOL must appear exactly once
              as a separate paragraph before the trailer paragraph
15aa963a6e1d: [same]

Every commit needs a bare FOLLOWING_AGENTS_PROTOCOL line as its own paragraph, then:

Following-Agents-Protocol: true
AI-Assisted: true
Assisted-by: <AGENT:MODEL [TOOL]>

No Signed-off-by, and no AI Co-Authored-By. See AGENTS.md § "Landing work". This needs an amend/rebase of your two commits — it is per-commit, so a new commit on top will not clear it. Entirely normal for a first contribution; nothing else in the protocol is outstanding.

Worth knowing before you spend more time

The original goal is already met. check-windows-portability passes on plain main today — the three video_engine.cpp errors were fixed by another change, and I closed #677 as already-landed after confirming its diff against main is empty. The remaining Windows red is windows-msvc-cpu / windows-msvc-vulkan, which are PR-only jobs with no main baseline (#584) and fail on every PR in the repo for unrelated reasons — this PR could never have turned them green.

So what is left here is the cleanup half, and it is still genuinely worth having: four hand-rolled setenv shims across the tree is a real smell and a shared platform_compat.h is where that should end up. Two things to sequence against, though: #524 conflicts hard with this (both edit tests/CMakeLists.txt and insert at the top of test_api_server.cpp, and it duplicates your M_PI and POSIX-stat work by other means), and #578 is a third spelling of the same setenv shim. Landing #524 first and rebasing would make this much smaller and easier to review.

Happy to look again once the header moves and the trailers land.