feat(sample): implement the three refused logprobs_mode variants (#238)

.agents/NOW.md

@@ -26,13 +26,13 @@ Work: exact-chunks on main `1ce0d662b`; sm_120 measured at `3d2581551`.
 | MXFP4 parity | c1 1.020, c2-c8 0.962-0.969. **#82 CLOSED: ptxas-lineage REFUTED** | TERMINAL: at parity |
 | ROW-SERVE-ASYNC-DENSE-MIRROR | **LANDED+dgx-VERIFIED** (`f9c969ae`): async mirror on classic dense Qwen3; SACRED 184/184 | Residual: sibling scope one-liner |
 | CPU levers (`QUANT-GGUF-CIQ-GEMM`) | Profile DONE: decode **47% threadpool sync**, prefill **~39% paged attn** | Parakeet encoder; attn dtype hoist |
-| Supported-models list | **LANDED**: FEATURES arch table CI-bound (33 archs) | — |
 | `/v1/videos` OpenAI shape | **MERGED** (#71): Sora `model`/`size`/`seconds` + `GET /{id}/content` | `row/SERVE-VIDEOS-REFS` PR open: reference conditioning |
 | `ENG-LOAD-DIRECT-UPLOAD` (#150) | **default ON:** verbatim weights VIEW the mmap; 27B load **1.54x warm / 1.61x cold** | merged qkv/gate_up + lm_head need the device |
 | Vulkan 27B | decode **MET 4.36 vs 4.35**. **LOADMEM: load held the model TWICE, 100.759 -> 53.413 GiB** | Load-phase host build is the new peak |
 | `BACKEND-ROCM` | **(b) fix in; #140 gfx1201 hipBLAS + Gemma-4 MoE landed; W0 green 4 archs** | compile + M2 ([spec](specs/rocm-unified-memory-b.md)) |
 | TP spike #287 (PR #143) | **TP-W1 LANDED**: rank-group table + TP handle (6/6); DSR leak FIXED (unblocks #127/#154/#155) | TP-W2 (linears + loader) |
 | Release | **ACTIVE; required W1-W11/W13 implemented in #196** | Finish hosted ten-SM proof; rebase/push; run full eight-tuple dry run |
+| `logprobs_mode` (#238) | **3 stubs -> all 4 work** | `logprob_token_ids` half |
 | Surface coverage (`ARCH-ONE-SURFACE`) | ROW 8 + #139; **embeddings live (#137): model, runner, ABI v15, endpoint, fold 4/4-231** | Real-checkpoint oracle cosine |
 
 In-flight, default-OFF, not pushed: see the row's spec.

.agents/coordination.md

@@ -1537,6 +1537,17 @@ public-doc change. Does NOT touch the roadmap issue table — PR #235 already
 registers #231 there and duplicating the row would guarantee a keyed-record
 conflict.
 
+**`logprobs_mode` modes (`SAMPLE-LOGPROB-TOKEN-IDS`, 2026-08-10, `CLAIM-SAMPLE-LOGPROBS-MODE`, issue #238).** Claude Code (claude-opus-5), isolated worktree
+`/home/mudler/_git/vllm.cpp-logprobs-mode`, branch `row/SAMPLE-LOGPROBS-MODE`, rebased onto
+`origin/main` `5e67fcc2`. Spec [logprobs-mode.md](specs/logprobs-mode.md). Scope: the three
+unimplemented `logprobs_mode` values and the deletion of the runtime refusal, in
+`src/vllm/v1/sample/sampler.{h,cpp}` plus four cases in
+`tests/vllm/v1/sample/test_sampler.cpp`. CPU-only; NO kernel, vt op, ABI, CMake, model file or
+GPU. Row moves `INVENTORIED` -> `PARTIAL`, NOT `ACTIVE`: `logprob_token_ids` generative scoring
+and the config/CLI plumbing to select a mode from outside the library are both still absent.
+Records a spec-after-code ordering deviation in the spec preamble rather than hiding it behind
+commit order.
+
 | Claim | Row IDs | Agent | Worktree / remote dir | Branch | Owned scope | State | Last update |
 |---|---|---|---|---|---|---|---|
 | `CLAIM-SPEC-DSPARK` | `SPEC-DSPARK` (`ACTIVE`) | Claude Code (opus-5), helper role | isolated worktree `/home/mudler/_git/vllm.cpp-spec-dspark`; CPU-only so far, NO build, NO GPU, NO download | `row/SPEC-DSPARK`, base `origin/main` `bc6e3d72`; NOT PUSHED, no PR yet (remote step PENDING developer authority) | The DSpark spike, records-only in this commit: NEW `.agents/specs/dspark-spec-decode.md`, the `SPEC-DSPARK` engine-matrix row + section/total counters, the feature-matrix §8 DSpark row, the superseded grounding-note header, this claim, `.agents/NOW.md`, and the `docs/STATUS.md`/`docs/FEATURES.md`/`docs/BENCHMARKS.md` one-liners. **NON-COLLISION:** touches NO `src/`, `include/`, `tests/`, `examples/` or CMake path. Implementation slices W1-W6 follow under this same claim. | `ACTIVE` | 2026-08-09 — spike committed. DSpark = the landed DFlash lane + Markov logit-bias head + sequential block sampling + anchor-as-first-prediction layout + `d2t` reduced vocab + method/config resolution + Speculators-format translation; upstream surface is 1613 lines over 5 files, 3 of them DFlash subclasses. Draft checkpoints exist for both gate models and for the 4B pair the upstream test uses; DeepSeek-V4 DSpark is out of scope (HW-blocked). NEXT: W1 config slice (CPU, RED = `speculative.cpp:44` rejects `"dspark"` today) and R1, prove the pinned oracle `555967922` actually RUNS DSpark (it forces the V2 runner). PENDING developer authority: checkpoint downloads, dgx GPU time, push/draft-PR. |

.agents/engine-matrix.md

@@ -39,14 +39,14 @@ forensics: roadmap_v1.md and the parity ledger.
 | Engine and scheduling | 27 | 6 | 3 | 1 | 3 | 6 | 2 | 2 | 4 |
 | KV cache and memory | 21 | 7 | 3 | 1 | 2 | 1 | 2 | 0 | 5 |
 | Parallelism | 6 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 5 |
-| Sampling and generation | 15 | 4 | 2 | 0 | 0 | 3 | 0 | 1 | 5 |
+| Sampling and generation | 15 | 4 | 3 | 0 | 0 | 3 | 0 | 1 | 4 |
 | Structured output and tools | 7 | 0 | 3 | 0 | 0 | 2 | 0 | 0 | 2 |
 | Speculative decoding | 21 | 0 | 0 | 1 | 0 | 5 | 0 | 4 | 10 |
 | Serving, API, CLI, library | 27 | 10 | 2 | 0 | 1 | 6 | 2 | 1 | 5 |
 | LoRA and adapters | 2 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 1 |
 | Long context and attention | 10 | 5 | 0 | 0 | 1 | 0 | 1 | 0 | 3 |
 | Loading, tokenizer, config | 10 | 3 | 3 | 0 | 0 | 1 | 1 | 1 | 1 |
-| **Total** | **146** | **36** | **16** | **3** | **8** | **24** | **8** | **9** | **41** |
+| **Total** | **146** | **36** | **17** | **3** | **8** | **24** | **8** | **9** | **40** |
 
 ## Engine core and scheduling
 
@@ -130,7 +130,7 @@ lifecycle are unchanged.
 | `SAMPLE-PHILOX` | Torch-Philox bit-exact stochastic parity | T1 | `vllm/v1/sample/ops/topk_topp_sampler.py:70`; `vllm/v1/sample/sampler.py:243` | - | - | `planned: specs/philox-rng-parity.md` | `INVENTORIED` | - |
 | `SAMPLE-LOGPROBS` | Token logprobs payload end to end | T1 | `vllm/logprobs.py:12,157,175`; `vllm/v1/engine/logprobs.py:29,69,348`; `vllm/v1/outputs.py:28,38`; `vllm/v1/core/sched/scheduler.py:1815-1836`; `vllm/entrypoints/openai/completion/serving.py:652`; `vllm/entrypoints/openai/chat_completion/serving.py:1114,1141`; `tests/v1/sample/test_logprobs.py:303` | `include/vllm/logprobs.h` (Logprob/LogprobsOnePosition/SampleLogprobs + AppendLogprobsForNextPosition); `include/vllm/v1/engine/logprobs.h`+`src/vllm/v1/engine/logprobs.cpp` (LogprobsProcessor); `src/vllm/v1/outputs.cpp:24` (LogprobsTensors::slice_request); `src/vllm/v1/worker/gpu/runner.cpp:1272` (ModelRunnerOutput.logprobs); `src/vllm/v1/core/sched/scheduler.cpp:674` (slice -> EngineCoreOutput.new_logprobs); `src/vllm/v1/engine/output_processor.cpp` (LogprobsProcessor integration -> CompletionOutput.logprobs); `src/vllm/entrypoints/openai/serving_utils.cpp` (BuildCompletionLogProbs/BuildChatLogprobs); `src/vllm/entrypoints/openai/protocol.cpp` (CompletionLogProbs/ChatCompletionLogProbs to_json); `src/vllm/entrypoints/openai/serving_{completion,chat}.cpp` | `tests/vllm/entrypoints/openai/test_logprobs.cpp:67,103` (serialization vs vLLM oracle, RED-first N vs N+1; LogprobsProcessor accumulation + inertness `:137,167`); `tests/vllm/entrypoints/openai/test_serving.cpp:411,668` (e2e through the CPU engine: logprobs=K + chat top_logprobs, inert-when-off `:467`). Closing record [parity-ledger.md#L741](parity-ledger.md#L741) 2026-07-27 W5 row. **#231 (2026-08-09): `logprobs=-1` crashed the engine** — the sentinel was preserved instead of widened, routing live requests into the sampler's raw-vocab arm (`sampler.py:122-125`), whose empty ids/ranks `UpdateSampleLogprobs` indexes anyway. Fixed by mirroring `gpu_input_batch.py:434-440` (widen to `vocab_size` at admission); the recorded `-1` deviation is GONE. `tests/vllm/v1/test_llm_engine.cpp` (full-vocab dict e2e, RED = SIGSEGV; finite-k no-regression) + `tests/vllm/v1/worker/test_input_batch.cpp` (widening at admission, paired and alone) — [logprobs-all-sentinel.md](specs/logprobs-all-sentinel.md) | [sampling-controls-c7.md](specs/sampling-controls-c7.md) (W5) | `DONE` | `ecda3ce1` |
 | `SAMPLE-PROMPT-LOGPROBS` | Prompt logprobs (payload plumbing + serialization done; runner prompt-position logits SOURCE pending) | T1 | `vllm/v1/engine/logprobs.py:121`; `vllm/v1/worker/gpu_model_runner.py:3842` (`_get_prompt_logprobs_dict`); `vllm/sampling_params.py:303` | payload path landed: `src/vllm/v1/engine/logprobs.cpp:75,100` (`UpdatePromptLogprobs`/`pop_prompt_logprobs`); `include/vllm/v1/engine/types.h:129,161` (`ModelRunnerOutput.prompt_logprobs_dict`, `EngineCoreOutput.new_prompt_logprobs_tensors`); `src/vllm/v1/core/sched/scheduler.cpp:688` (prompt_logprobs_dict slice); `src/vllm/v1/engine/output_processor.cpp:224` (`RequestOutput.prompt_logprobs`). **RESIDUAL: the runner does not yet compute prompt-position logits (lm_head over prompt tokens) — the tensor SOURCE; a runner/prefill addition adjacent to C5** | `tests/vllm/entrypoints/openai/test_logprobs.cpp:137,167` (LogprobsProcessor accumulation/inertness cover the shared consume path; the prompt-only source is inert until the runner lands) | `planned: specs/prompt-logprobs.md` | `PARTIAL` | - |
-| `SAMPLE-LOGPROB-TOKEN-IDS` | `logprob_token_ids` generative scoring and `logprobs_mode` variants beyond raw/processed (`SAMPLE-LOGPROBS` covers the payload only); carried from porting-inventory §6 (T1) at the v1 fold | T1 | `vllm/sampling_params.py:278,727`; `vllm/config/model.py:82,221` | - | - | `planned: specs/logprob-token-ids.md` | `INVENTORIED` | - |
+| `SAMPLE-LOGPROB-TOKEN-IDS` | `logprob_token_ids` generative scoring + the `logprobs_mode` variants (`SAMPLE-LOGPROBS` covers the payload only); carried from porting-inventory §6 (T1) at the v1 fold | T1 | `vllm/sampling_params.py:278,727`; `vllm/config/model.py:82,221`; `vllm/v1/sample/sampler.py:85-93,255-302` (the mode snapshots); `:151-225` (`gather_specific_token_logprobs`) | **`logprobs_mode` LANDED (#238):** all four modes in `src/vllm/v1/sample/sampler.cpp:310,313,315` (`Sampler::forward` raw snapshot per mode) and `:203,376` (`Sampler::sample` `processed_out` at the two upstream snapshot points) + `include/vllm/v1/sample/sampler.h:55` (enum semantics) and `:95` (`sample` out-param). The runtime refusal is GONE. **RESIDUAL: `logprob_token_ids` generative scoring, and the config/CLI/`SamplingParams` plumbing to select a mode from outside the library — the modes are reachable only by constructing a `Sampler` directly** | `tests/vllm/v1/sample/test_sampler.cpp:404` (4 cases over one shared logits row: `raw_logits` unnormalized, `raw_logprobs` default regression, `processed_logits` top-k mask, `processed_logprobs` renormalized over the kept set; RED-first — 3 threw on the refusal) | [logprobs-mode.md](specs/logprobs-mode.md) | `PARTIAL` | `CLAIM-SAMPLE-LOGPROBS-MODE` |
 | `SAMPLE-LOGIT-FILTERS` | Logit bias, allowed-token IDs, bad words | T1 | `vllm/sampling_params.py:318,321,337,341,388-413,659-698`; `vllm/v1/sample/sampler.py:396`; `vllm/v1/worker/gpu_input_batch.py:446-471`; `vllm/entrypoints/openai/completion/protocol.py:369-371`; `tests/v1/sample/test_sampler.py:367,413`; `tests/v1/sample/test_sampling_params_e2e.py:106,147` | `include/vllm/sampling_params.h`+`src/vllm/sampling_params.cpp` (fields+validation); `src/vllm/entrypoints/openai/protocol.cpp` (`ParseLogitFilters`/`ApplyLogitFilters` clamp); `src/vllm/v1/worker/gpu/input_batch.cpp:255,344` (per-slot wiring+condense/swap); `src/vllm/v1/engine/input_processor.cpp` (bad_words tokenization); `src/vllm/v1/sample/sampler.cpp:239`; `src/vllm/v1/sample/logits_processor/builtin.cpp:41`; `src/vllm/v1/sample/ops/bad_words.cpp:13,55` | `tests/vllm/v1/sample/test_logits_processors.cpp:121,163,200`; `tests/vllm/test_sampling_params.cpp` (bad_words/allowed_token_ids validation); `tests/vllm/entrypoints/openai/test_protocol.cpp` (logit_bias clamp+parse); `tests/vllm/v1/worker/test_input_batch.cpp` (wiring, RED-first); `tests/vllm/v1/test_input_processor.cpp` (bad_words tokenization) | [sampling-controls-c7.md](specs/sampling-controls-c7.md) (`SAMPLE-LOGIT-FILTERS`) | `ANCHOR-BACKFILL` | `CLAIM-ROADMAP-C7` |
 | `SERVE-COMPLETION-LONGTAIL` | Best-of, echo, suffix, user request fields | T1 | `vllm/entrypoints/openai/completion/protocol.py:56,67,70`; `tests/entrypoints/openai/completion/test_token_in_token_out.py:56` | echo parse only `include/vllm/entrypoints/openai/protocol.h:196`; `src/vllm/entrypoints/openai/protocol.cpp:204,295` | acceptance-only `tests/vllm/entrypoints/openai/test_conformance.cpp:589` | `planned: specs/completions-longtail-fields.md` | `PARTIAL` | - |
 | `SAMPLE-BEAM` | Beam search: an OUTER loop over the engine (NOT a core-sampler param). Each step runs ONE decode per active beam (`logprobs=2*beam_width`, `max_tokens=1`, the beam temperature), expands each beam to those next tokens (`cum_logprob += logprob`), keeps the top-`beam_width` by the length-penalty score `get_beam_search_score = cum_logprob / seq_len**length_penalty` (`seq_len` INCLUDES the prompt, −1 when the last token is EOS), retires EOS-terminated beams into `completed`, and after `max_tokens` (or once all beams complete) returns the top-`beam_width` completed beams as multiple outputs (reuses the `SAMPLE-N` multi-output aggregation seam). The scoring + top-k-beam selection + EOS + length-penalty are DETERMINISTIC ⇒ token-EXACT vs vLLM, gated model-free on a hand-computed toy tree. `std::stable_sort` DESCENDING reproduces vLLM's `sorted(reverse=True)` tie behaviour. OpenAI-endpoint `use_beam_search` is WIRED on both `/v1/completions` and `/v1/chat/completions` over BOTH engine seams, REAL vLLM-0.26 surface: the SYNC `LLMEngine` (`BeamSearch`, offline.py) AND the PRODUCTION AsyncLLM HTTP server (`BeamSearchAsync`, online.py) — the server (`examples/server/main.cpp`) holds an AsyncLLM, so a beam request there now RUNS instead of raising "requires the synchronous engine". `BeamSearchAsync` drives the AsyncLLM per-beam single-token `generate` (pre-tokenized overload added to `AsyncLLM`) and calls the SAME model-free `BeamSearchStep`/`get_beam_search_score` — the algorithm is shared verbatim via a template driver body, only the engine object differs (mirrors online.py mirroring offline.py). GATE: `BeamSearchAsync` returns beams token-IDENTICAL to sync `BeamSearch` over the same synthetic CPU model (tokens/order/scores/text), for beam_width 1/2/3. CONCURRENCY FINDING: per-step beam decodes are issued SEQUENTIALLY (one isolated request each), byte-identical to the sync driver; online.py's `asyncio.gather` per-beam CONCURRENT stepping is a NAMED RESIDUAL (AsyncLLM supports concurrent requests — a future throughput optimization, correctness-first here). OTHER RESIDUALS: streaming beam (rejected like upstream), C-ABI beam params, grammar-constrained beam search (structured-output bitmask branch), encoder-decoder/LoRA beams | T1 | `vllm/entrypoints/generate/beam_search/utils.py:18,102,112,137,156`; `vllm/entrypoints/generate/beam_search/offline.py:58,118,160,193,291-327`; `vllm/entrypoints/generate/beam_search/online.py:28-220` (the OpenAI-serving beam generator); `vllm/entrypoints/openai/completion/protocol.py:260`/`chat_completion/protocol.py:589` (`to_beam_search_params`); `vllm/entrypoints/openai/completion/serving.py:173-205`/`chat_completion/serving.py:319-343` (`use_beam_search` routing); `vllm/sampling_params.py:1114` (`BeamSearchParams`) | `include/vllm/entrypoints/beam_search.h` + `src/vllm/entrypoints/beam_search.cpp` (model-free core + shared template `BeamSearchDrive` + `BeamSearch(LLMEngine&, …)` sync driver + `BeamSearchAsync(AsyncLLM&, …)` production driver); `include/vllm/v1/engine/async_llm.h`+`src/vllm/v1/engine/async_llm.cpp` (pre-tokenized `add_request`/`generate` overloads the async beam driver steps on); `include/vllm/entrypoints/openai/protocol.h`+`src/vllm/entrypoints/openai/protocol.cpp` (`use_beam_search`/`length_penalty` fields + `to_beam_search_params`, both requests); `src/vllm/entrypoints/openai/serving_completion.cpp` + `serving_chat.cpp` (`use_beam_search` routes to `BeamSearchAsync` when async-backed, else `BeamSearch` + `set_beam_search_tokenizer`); `examples/server/main.cpp` (wires `set_beam_search_tokenizer` on the production handlers so beam runs on the HTTP server); `CMakeLists.txt` — anchor `src/vllm/entrypoints/beam_search.cpp:59` | `tests/vllm/entrypoints/test_beam_search.cpp` (model-free token-EXACT tree) + `tests/vllm/v1/test_llm_engine.cpp` (e2e beam over the CPU engine; `BeamSearchAsync` == sync `BeamSearch` token-identical for bw 1/2/3) + `tests/vllm/entrypoints/openai/test_serving.cpp` (endpoint `use_beam_search` choices IDENTICAL to the direct driver, completion + chat, over BOTH the sync AND the production AsyncLLM engine; `to_beam_search_params` round-trip; streaming-beam + tokenizer-less async beam rejected) — anchor `tests/vllm/entrypoints/test_beam_search.cpp:82` | [sampling-controls-c7.md](specs/sampling-controls-c7.md) (`SAMPLE-BEAM`) | `ACTIVE` | `CLAIM-C7-BEAM-ASYNC` |

.agents/roadmap_v1.md

@@ -40,6 +40,7 @@ issue is not yet placed. Keyed record: update in place, never append.
 | [#250](https://github.com/mudler/vllm.cpp/issues/250) | — | `a5b52047` reached main without a task branch, and `check-role-discipline` cannot be waived | bug |
 | [#243](https://github.com/mudler/vllm.cpp/issues/243) | — | `vllm-feature-gap-analysis.md` is a stale 2026-07-28 snapshot: 9 of 16 HIGH/MED gaps have since landed | bug |
 | [#242](https://github.com/mudler/vllm.cpp/issues/242) | — | `docs/FEATURES.md` drift: arch counts say 30 (registry has 35), multimodal-over-HTTP marked ☐ though W1-W3 landed | bug |
+| [#238](https://github.com/mudler/vllm.cpp/issues/238) | `SAMPLE-LOGPROB-TOKEN-IDS` | `logprobs_mode`: three of four modes are runtime-refused stubs | bug |
 | [#230](https://github.com/mudler/vllm.cpp/issues/230) | — | `test_agent_record.py`: 7 issue-intake tests never run, and error when they do | bug |
 | [#224](https://github.com/mudler/vllm.cpp/issues/224) | `ENG-DOCS-SITE` | Publish `docs/` as a GitHub Pages site without owning a second copy | feature |
 | [#203](https://github.com/mudler/vllm.cpp/issues/203) | `BACKEND-VULKAN` | Vulkan on unified memory holds TWO copies of the weights: 27B peaks at 100.8 GiB RSS and OOM-reboots a Spark | bug |