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

CMakeLists.txt

@@ -1811,6 +1811,10 @@ endif()
 if(VLLM_CPP_SERVER)
   find_package(Threads REQUIRED)
   target_sources(vllm PRIVATE src/vllm/entrypoints/openai/api_server.cpp)
+  # ARCH-ONE-SURFACE: the server ENTRY POINT (flag parsing + engine/serving
+  # construction) lives in the library so examples/server can be a thin client of
+  # the C ABI's vllm_server_main (v17). It shares api_server.cpp's httplib gate.
+  target_sources(vllm PRIVATE src/vllm/entrypoints/openai/server_main.cpp)
   target_compile_definitions(vllm PUBLIC VLLM_CPP_SERVER)
   target_link_libraries(vllm PUBLIC Threads::Threads)
   # third_party/httplib/httplib.h is reached as <httplib/httplib.h> (third_party

examples/CMakeLists.txt

@@ -67,7 +67,11 @@ endif()
 # The OpenAI HTTP server example is gated on the vendored cpp-httplib transport.
 if(VLLM_CPP_SERVER)
   add_executable(server server/main.cpp)
-  target_link_libraries(server PRIVATE vllm::vllm)
+  # ARCH-ONE-SURFACE: server/main.cpp is a THIN CLIENT of the public C ABI
+  # (vllm_server_main, v17) -- it includes vllm.h and nothing else, so it links the
+  # PACKAGED shared library exactly as an out-of-tree consumer would, not the
+  # internal C++ target.
+  target_link_libraries(server PRIVATE vllm::shared)
   vllm_cpp_set_warnings(server)
   if(VLLM_CPP_BUILD_TESTS)
     add_test(NAME test_server_help COMMAND $<TARGET_FILE:server> --help)

include/vllm.h

@@ -129,8 +129,20 @@ extern "C" {
  * other's tasks LOUDLY: vllm_complete/vllm_chat on a pooling engine name
  * vllm_embed, and vllm_embed on a text engine names vllm_complete — the
  * SupportsTranscription-refusal precedent (v11) applied to the pooling task.
- * Purely additive — no struct changed; zero values preserve behaviour. */
-#define VLLM_ABI_VERSION 16
+ * Purely additive — no struct changed; zero values preserve behaviour.
+ *
+ * v17 — vllm_server_main: RUN THE OPENAI SERVER from the public surface.
+ * examples/server was the deepest ONE SURFACE breach (36 internal headers: the
+ * engine, the serving layers, metrics, the video and ASR seams), which is why it
+ * carried an example-abi-allowlist entry. That construction moved INTO the
+ * library (vllm/entrypoints/openai/server_main.h) and the example is now a thin
+ * client of this call. argv rather than a params struct is deliberate: the
+ * server takes ~57 flags and gains more with every serving feature, and a
+ * mirrored C struct would put that churn in the ABI where every field is
+ * permanent. The flag surface mirrors vLLM's cli_args.py, which is the real
+ * contract. Embedders wanting programmatic control keep the granular entry
+ * points. Purely additive. */
+#define VLLM_ABI_VERSION 17
 
 /* ── Export macro ─────────────────────────────────────────────────────────────
  * Marks the symbols that make up the stable ABI. Default visibility now; Task 3
@@ -792,6 +804,23 @@ VLLM_API const char* vllm_last_error(void);
  * not free. */
 VLLM_API const char* vllm_version(void);
 
+/* ── OpenAI-compatible server ─────────────────────────────────────────────────
+ * Parse `argv` and RUN the OpenAI-compatible HTTP server until it exits,
+ * returning the process exit code (0 on clean shutdown). `--help` prints usage
+ * and returns 0; a bad argument or a startup failure prints the reason and
+ * returns non-zero. Never throws across this boundary.
+ *
+ * This is what `vllm-server` is: examples/server is a thin client of this call.
+ * It serves /v1/chat/completions, /v1/completions, /v1/models, /v1/embeddings,
+ * and — when the matching flags are supplied — /v1/videos (MiniMax-H3) and
+ * transcription, all through the SAME library seams the granular entry points
+ * below drive, so HTTP and FFI cannot drift.
+ *
+ * BLOCKS for the lifetime of the server. `argv` must hold `argc` NUL-terminated
+ * strings and stay valid for the duration; the library does not take ownership.
+ * The conventional argv[0] program name is expected at index 0. */
+VLLM_API int32_t vllm_server_main(int32_t argc, char** argv);
+
 /* The ABI version the library was built with (compare against VLLM_ABI_VERSION). */
 VLLM_API int32_t vllm_abi_version(void);
 

scripts/example-abi-allowlist.txt

@@ -24,7 +24,6 @@
 # --- Capability drivers whose FAST PATH is reachable ONLY here, not through the ABI ---
 examples/deepseek_v4_gen | fold=ARCH-ONE-SURFACE | DeepSeek-V4-Flash keep-quant GGUF greedy decode (DeepseekV4ForwardGguf(Cached) + DeepseekV4KvCache) is CLI-only; the registered DeepseekV4ForCausalLM forward is a W3-W8 stub (deepseek_v4_registry.cpp:22). Grow ABI keep-quant GGUF load+decode, rewrite as ABI client, delete the bespoke forward
 examples/laguna_gen | fold=ARCH-ONE-SURFACE | Laguna-S-2.1 keep-quant GGUF (multi-shard) + NVFP4 W4A4 device-resident decode (LagunaForwardGguf(Cached), Marlin residents, fp4-shared) is CLI-only; registered LagunaForCausalLM forward VT_CHECK(false)s on non-bf16 (laguna.cpp:156). Grow ABI, rewrite as client, delete bespoke forward
-examples/server | fold=ARCH-ONE-SURFACE | The reference OpenAI server constructs the engine, metrics, video_runner and mm seam directly from internal C++ headers (LoadedEngine/AsyncLLM, minimax_h3.h, chat_mm). It should stand on the public surface (C ABI, or a curated public C++ API the ABI wraps). Grow the surface, rewrite the server against it
 
 # --- Dev / diagnostic tools: NO permanent exemption (developer-directed 2026-08-07) ---
 # Every one is a transition-tracker like the drivers above; the allowlist only shrinks.

src/capi/vllm_c.cpp

@@ -44,6 +44,7 @@
 #include "vllm/model_executor/models/minimax_h3.h"    // mux argv (v12)
 #include "vllm/multimodal/parakeet_transcription.h"     // vllm_transcribe (v11)
 #include "vllm/multimodal/minimax_h3_video.h"          // vllm_video_* (v12)
+#include "vllm/entrypoints/openai/server_main.h"   // vllm_server_main (v17)
 #include "vllm/outputs.h"
 #include "vllm/sampling_params.h"
 #include "vllm/transformers_utils/hf_config.h"  // PeekHfArchitectures (v11)
@@ -1615,6 +1616,22 @@ VLLM_API const char* vllm_version(void) {
   return kVersion.c_str();
 }
 
+VLLM_API int32_t vllm_server_main(int32_t argc, char** argv) {
+  // The server owns its own error reporting on stderr (it is a PROCESS entry
+  // point, not a request call), so this does not set vllm_last_error. What it
+  // must guarantee is that nothing throws across the C boundary.
+  try {
+    return static_cast<int32_t>(
+        vllm::entrypoints::openai::VllmServerMain(static_cast<int>(argc), argv));
+  } catch (const std::exception& e) {
+    std::fprintf(stderr, "vllm_server_main: %s\n", e.what());
+    return 1;
+  } catch (...) {
+    std::fprintf(stderr, "vllm_server_main: unknown error\n");
+    return 1;
+  }
+}
+
 VLLM_API int32_t vllm_abi_version(void) { return VLLM_ABI_VERSION; }
 
 }  // extern "C"