arch(ARCH-ONE-SURFACE): the OpenAI server becomes a THIN ABI CLIENT — vllm_server_main, ABI v17

[localai-bot]

Why

examples/server was the deepest breach of the ONE SURFACE directive (.agents/specs/one-surface-abi.md): 1046 lines reaching into 36 internal headers to construct the engine, the serving layers, metrics, the video seam and the ASR seam by hand. It carried the largest entry in scripts/example-abi-allowlist.txt, whose fold order is fixed — grow the public surface, rewrite the example against it, delete the parallel implementation.

Grown

VLLM_API int32_t vllm_server_main(int32_t argc, char** argv);   /* ABI v17, additive */

The construction moved into the library verbatim as vllm::entrypoints::openai::VllmServerMain (src/vllm/entrypoints/openai/server_main.{h,cpp}); src/capi wraps it so nothing throws across the C boundary.

argv rather than a params struct is deliberate. The server takes ~57 flags and gains more with every serving feature; mirroring them into a C struct would put that churn in the ABI, where every field is permanent. The flag surface already has a contract — vLLM's cli_args.py, which this mirrors — so argv is the stable interface. Embedders wanting programmatic control keep the granular entry points (vllm_engine_load, vllm_chat, vllm_video_generate, vllm_transcribe).

Rewritten

examples/server/main.cpp is now 23 lines:

#include "vllm.h"
int main(int argc, char** argv) { return vllm_server_main(argc, argv); }

Internal includes: 0. It links vllm::shared rather than the internal vllm::vllm target, so it builds exactly as an out-of-tree consumer does — which is what actually tests the boundary. HTTP and FFI cannot drift: the server the ABI runs is the server this binary runs.

Gate closed

The examples/server line is removed from scripts/example-abi-allowlist.txt. That file reds on a stale entry for a now-clean example, so removing it is the enforcement closing, not bookkeeping. Eight examples remain tracked (laguna_gen, deepseek_v4_gen, the benches, the introspection tools).

Verified

Clean configure + build from this branch on Thor (sm_110):

• CONFIGURE_RC=0, BUILD_RC=0
• ./server --help runs through the ABI and prints the full flag surface, EXIT=0
• Binary size 32,780,560 → 70,304 bytes — it no longer statically carries the engine, which is the fold in one number

Not claimed

I did not run the server against a live model in this row; the verification is build + --help + the boundary check. The moved construction is byte-identical to what shipped, so behaviour should be unchanged, but a live serving smoke test is worth having before this is relied on in production.