one-surface(parakeet): fold Parakeet ASR onto the C ABI (ROW 1)

.agents/NOW.md

@@ -24,10 +24,10 @@ Working head: `row/backend-rocm-w0` (#41). Prior: benchmark checkpoint
 | MXFP4 parity | c1 1.020, c2-c8 0.962-0.969. **#82 CLOSED: ptxas-lineage REFUTED (A/B ties our+vLLM PTX all ptxas/JIT; +10us=engine context, not codegen)** | 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**. **G5 not next** | Parakeet encoder; attn dtype hoist |
-| Supported-models list (`row/DOCS-SUPPORTED-MODELS-MATRIX`) | **DRAFT PR**: FEATURES per-arch table CI-bound to registry (30 archs) | Reviewer merge |
+| 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 |
 | `BACKEND-ROCM` W0 | Skeleton in; **HIP never compiled** (no AMD HW) | #41 contributors build it; a compile error IS the deliverable |
-| Surface coverage (`ARCH-ONE-SURFACE`) | **Guard LANDS** `check-surface-coverage.py` (2 axes): examples+FEATURES caps→ABI or tracked | PR #120 |
+| Surface coverage (`ARCH-ONE-SURFACE`) | **ROW 1 LANDED (#121)**: Parakeet ASR on the surface (`vllm_transcribe` v11, `/v1/audio/transcriptions`, ratchet 12→11) | Next fold row |
 
 In-flight (default-OFF, not pushed): `laguna-fp4proj-prod`, laguna
 bf16/legacy/pipeline-gemv, `ds4-hc-expand-fuse`.

.agents/specs/one-surface-abi.md

@@ -1,6 +1,6 @@
 # ONE SURFACE — every capability ships through the C ABI
 
-Row: `ARCH-ONE-SURFACE`. Status: **AUDIT DONE, remediation NOT started.**
+Row: `ARCH-ONE-SURFACE`. Status: **AUDIT DONE; remediation IN PROGRESS — ROW 1 (Parakeet ASR / audio transcription) LANDED 2026-08-07: ABI v11 `vllm_transcribe`, live `/v1/audio/transcriptions`, registry refuse-by-task, example folded, ratchet 12 -> 11.**
 
 ## The defect
 
@@ -34,9 +34,12 @@ stay OPEN. The complete, code-grounded matrix (all 30 archs + every off-registry
 | DeepSeek-V4 | YES | KV spec is a "never exercised" stub; registry forward discards attn_meta/kv | `examples/deepseek_v4_gen` | 240 lines |
 
 This table also UNDER-COUNTS: it omits Parakeet ASR (a 5th off-surface capability, landed
-`fd2259d8`) and the partial internal-reachers `minimax_h3_mux`, `bench`, `tokenize`,
-`dump_container`, `dequant_nvfp4`, `quant_gemm_bench` — 12 of 13 example binaries include
-non-public headers today (only `examples/cli` is clean). The full list is the audit spec.
+`fd2259d8` — **CLOSED 2026-08-07 by ROW 1**: `vllm_transcribe` on ABI v11, live
+`/v1/audio/transcriptions`, registry refuse-by-task, example rewritten as a `vllm.h`
+client, ratchet 12 -> 11) and the partial internal-reachers `minimax_h3_mux`, `bench`,
+`tokenize`, `dump_container`, `dequant_nvfp4`, `quant_gemm_bench` — 11 of 13 example
+binaries still include non-public headers (`examples/cli` and `examples/parakeet_transcribe`
+are the clean ABI clients). The full list is the audit spec.
 
 `examples/server/main.cpp` also carries ~32 internal includes (54 direct `MiniMaxH3`
 references), i.e. it re-implements wiring rather than consuming a library entry point. So
@@ -137,5 +140,11 @@ embedder produce an MP4 without reinventing the command: the library composes it
 
 ## NOT claimed
 
-No ABI work has been done. The shape above is a proposal, not an implementation,
-and it has not been reviewed against an embedder other than LocalAI.
+The VIDEO ABI shape above is a proposal, not an implementation, and it has not
+been reviewed against an embedder other than LocalAI. The ONE landed slice is
+audio transcription (ROW 1, 2026-08-07): `vllm_transcribe` + params/result
+structs on ABI v11, the `ParakeetTranscriber` library seam, task-conditional
+`/v1/audio/transcriptions`, registry refuse-by-task, and the example as a thin
+`vllm.h` client — gated byte-identical to the pre-fold transcripts. Video,
+Laguna/DeepSeek/Kimi fast decode, embeddings and multimodal input remain open
+rows of this program.

.agents/specs/surface-coverage-2026-08-07.md

@@ -27,7 +27,7 @@ The four surfaces, and the public boundary the guard draws:
 | 1 | **MiniMax-H3 video+audio generation** | NO (off-registry diffusion) | `/v1/videos` ONLY via an example-injected `VideoRunner` | NO | `examples/minimax_h3_gen` + `examples/minimax_h3_mux` (whole pipeline) |
 | 2 | **Laguna fast decode** | yes, but forward is a stub | no (stub `VT_CHECK`s non-bf16) | no | `examples/laguna_gen` (keep-quant GGUF + NVFP4 W4A4) |
 | 3 | **DeepSeek-V4 fast decode** | yes, but forward is a W3 stub | no (stub) | no | `examples/deepseek_v4_gen` (keep-quant GGUF) |
-| 4 | **Audio transcription** | NO (Whisper/Voxtral/Parakeet off-registry) | no (`/v1/audio/*` = batch residual) | no | `examples/parakeet_transcribe`; Whisper/Voxtral test-only |
+| 4 | **Audio transcription** | **CLOSED (ROW 1)**: Parakeet CTC/RNNT/TDT registered (transcription-only; Whisper/Voxtral still off-registry) | **live `/v1/audio/transcriptions`** (task-conditional; the run_batch line stays a residual) | **`vllm_transcribe` (ABI v11)** | library seam `ParakeetTranscriber`; example is a clean ABI client |
 | 5 | **Kimi-Linear incremental decode** | yes (recompute forward IS shared) | recompute only | no | `examples/kimi_linear_gen` (§18/§19 paged-incremental + resident loader) |
 | 6 | **Embeddings / pooling** | NO (all `is_pooling_model=false`) | no (`/v1/embeddings` = residual) | no | engine-side pooler exists (`ENG-POOLER-SEQ`), never invoked live |
 | 7 | **Multimodal input over HTTP/ABI** | 5 archs `supports_multimodal` | image seam only; tower not run in engine step | no (text-only chat) | `chat_mm.cpp` seam; towers test-only |
@@ -61,7 +61,7 @@ All three drivers run a PRIVATE host-argmax greedy loop, not the on-GPU sampler.
 | Lane | Registered | Code (file:line) | Server | C-ABI | Driver |
 |---|---|---|---|---|---|
 | MiniMax-H3 video+audio GEN | NO | `minimax_h3*.cpp` (~22 TUs), vt op `kMiniMaxH3` | `/v1/videos` via `set_video_runner` (example-injected only; `api_server.h:167`, `api_server.cpp:818`; library never sets it) | NO | `examples/minimax_h3_gen`, `examples/minimax_h3_mux` |
-| Parakeet/FastConformer ASR | NO (grep `parakeet_*.cpp` for `REGISTER_VLLM_MODEL` = 0) | `parakeet_encoder.cpp`, `parakeet_transducer.cpp`, `parakeet_audio_processor.cpp`; owns transcript logic (`ReadWav16BitMono`, `LoadVocab`, `DecodeIds` Metaspace decoder — bypasses `vllm::Tokenizer`) | NO | NO | `examples/parakeet_transcribe` (#89) |
+| Parakeet/FastConformer ASR | **YES (ROW 1)**: ParakeetForCTC/RNNT/TDT, `parakeet_registry.cpp` (SupportsTranscription-only; text paths refuse by task) | `parakeet_transcription.cpp` seam composes encoder/transducer/audio-processor; the example's private `ReadWav16BitMono`/`LoadVocab`/`DecodeIds` are DELETED (`vllm::Tokenizer` now decodes Metaspace split=true) | **`/v1/audio/transcriptions`** (task-conditional) | **`vllm_transcribe` (ABI v11)** | `examples/parakeet_transcribe` = thin `vllm.h` client |
 | Voxtral audio->text | NO (`VoxtralForConditionalGeneration` unregistered) | `voxtral.cpp` (`vllm::multimodal`) | NO (`/v1/audio/transcriptions` = `run_batch.cpp:188` residual) | NO | tests-only reachability |
 | Whisper audio encoder | NO | `whisper_audio.cpp:174` | NO | NO | tests-only callers |
 | Pooling / embeddings | NO (`is_pooling_model=false` in all 27) | `layers/pooler/*.cpp`, `pool/pooling_runner` (`ENG-POOLER-SEQ`) | NO (`/v1/embeddings` = residual) | NO | `PoolingRunner` test-only |
@@ -75,19 +75,21 @@ JSON sub-config, not a separate surface) — the model for how the others should
 
 Public boundary = `#include "vllm.h"` only. 13 example units; `examples/cli` (vllm-cli,
 links `vllm::shared`, `#include "vllm.h"` only, `cli/main.cpp:16`) is the sole clean ABI
-client. The other 12 reach `include/vllm/**` / `vt/**` and are transition-tracked in
-`scripts/example-abi-allowlist.txt`:
+client. **ROW 1 UPDATE (2026-08-07): `parakeet_transcribe` is the SECOND clean ABI
+client** — the Parakeet fold rewrote it against `vllm.h` + `vllm::shared` only, and the
+ratchet fell 12 -> 11. The remaining 11 reach `include/vllm/**` / `vt/**` and are
+transition-tracked in `scripts/example-abi-allowlist.txt`:
 
 - Capability drivers: `deepseek_v4_gen`, `laguna_gen`, `kimi_linear_gen`,
-  `minimax_h3_gen`, `minimax_h3_mux`, `parakeet_transcribe`, `server`.
+  `minimax_h3_gen`, `minimax_h3_mux`, `server`.
 - Dev/diagnostic (internal-by-nature, folded for consistency): `bench` (via
   `bench_core.h`), `tokenize`, `dump_container`, `dequant_nvfp4`, `quant_gemm_bench`.
 - Out of the gated `examples/` tree: `benchmarks/vulkan_gemm_ab.cpp` (Vulkan A/B harness).
 
 **Policy (developer-directed 2026-08-07): no permanent exemptions.** Every allowlist entry
 — drivers AND dev/diagnostic tools — is a transition-tracker pointing at a fold row; the
 guard fails on any internal include not tracked, and a shrink-only ratchet
-(`MAX_INTERNAL_REACHING = 12`) means the count can only fall as folds land, never grow to
+(`MAX_INTERNAL_REACHING`, 11 since ROW 1) means the count can only fall as folds land, never grow to
 admit a new violation. The public header set is DERIVED from the CMake install rules
 (exactly `include/vllm.h` today), not hardcoded. The guard catches BOTH breach vectors: a
 `#include "vllm/..."|"vt/..."|"src/..."` AND a CMake `-I` grant into the internal tree
@@ -129,7 +131,7 @@ lanes are leaves of `ARCH-ONE-SURFACE` (do not open parallel rows).
 | 1 | Video+audio gen | `vllm_video_generate` + job/status/content entry points (mirror `/v1/videos`; carry the `VideoRunner` internally, not example-injected) | rewrite `minimax_h3_gen`/`server` as clients; delete driver glue | L | H3 loaders; ffmpeg-mux boundary (ratified in `examples/`) |
 | 2 | Laguna fast decode | make the registered `LagunaForCausalLM` forward route the keep-quant/NVFP4 device path (retire the stub); load keep-quant GGUF/NVFP4 dirs through `vllm_engine_load` | rewrite `laguna_gen`; delete `LagunaForwardGguf*` | M | keep-quant load in the engine loader |
 | 3 | DeepSeek-V4 fast decode | same as (2) for `DeepseekV4ForCausalLM`; real MLA paged KV (retire the W3 stub) | rewrite `deepseek_v4_gen`; delete `DeepseekV4ForwardGguf*` | M | MLA paged-KV topology |
-| 4 | Audio transcription | `vllm_transcribe` + live `/v1/audio/transcriptions`; register a Whisper/Voxtral/Parakeet arch or an encoder lane | rewrite `parakeet_transcribe`; wire the route | M | encoder→text seam |
+| 4 | Audio transcription | **DONE (ROW 1, 2026-08-07)**: `vllm_transcribe` (ABI v11) + live `/v1/audio/transcriptions`; ParakeetForCTC/RNNT/TDT registered (SupportsTranscription mirror, refuse-by-task) | **DONE**: `parakeet_transcribe` rewritten as a `vllm.h` client (byte-identical transcript goldens); route live, task-conditional | M | encoder→text seam (LANDED: `ParakeetTranscriber`) |
 | 5 | Kimi-Linear incremental | expose the incremental decode path through the runner/engine (the recompute forward already routes) | rewrite `kimi_linear_gen` | S–M | `KimiDecodeCache` on the runner |
 | 6 | Embeddings/pooling | `vllm_embed`/pooling entry point + live `/v1/embeddings`; register a pooling arch (`is_pooling_model=true`); invoke `PoolingRunner` in the step | — | M | pooler live-wiring |
 | 7 | Multimodal input | multimodal-content entry point on `vllm_chat`; run the vision/audio tower in the engine step (`mm_features`→`ModelForwardInput.mm`) | wire `chat_mm` seam into the ABI | L | `MM-SERVE-E2E` engine mm-forward residual |

.agents/state.md

@@ -42031,3 +42031,71 @@ leaves (Kimi runner fold #279, Parakeet ASR #280). Reviewer findings 1-8 applied
 (quoted+angle includes, comment-stripped ABI tokenize, subprocess enforcement
 tests, ratchet equality pin, reachable-row-removal design note, meta-gap note). No
 CUDA build; no perf number owed; STATUS inside its char ratchet.
+
+## 2026-08-07 — ARCH-ONE-SURFACE ROW 1: Parakeet ASR folded onto the ONE surface (PR #121)
+<!-- state: 2026-08-07T23:30 -->
+
+**Landed** (`row/PARAKEET-ONE-SURFACE`, helper claim = PR #121, base `f98e1e48`):
+the first remediation slice of the ONE SURFACE program — audio transcription is
+now reachable by every consumer, gated BYTE-IDENTICAL to the pre-fold example.
+
+**Correctness anchor first.** Real `nvidia/parakeet-*` checkpoints were deleted
+post-#89, so a deterministic tiny CTC+RNNT fixture pair + clip was committed
+(`tests/vllm/models/fixtures/parakeet_e2e`, generator
+`scripts/mm/parakeet_e2e_fixture_gen.py`) and the transcript goldens were
+captured from the PRE-refactor binary at `main@f98e1e48` BEFORE any change
+(ctc: ids `3 4 3` / "atheat"; rnnt: 20 ids / "sss on on onssssss ...").
+`tests/vllm/models/test_parakeet_transcription_fold.cpp` holds seam ==
+replicated old pipeline == committed goldens, per head.
+
+**The fold, in the binding order.**
+- W1a tokenizer: `Tokenizer::FromHfJson` accepts Metaspace `split:true`
+  (MergedWithNext pre-split; merges cannot cross ▁) and a bare `Metaspace`
+  DECODER node selects HF's decode_chain rule (first token drops ▁) —
+  the guard at `tokenizer.cpp:554` implemented instead of refusing;
+  Mistral/Gemma Sequence chain regression-pinned
+  (`tests/vllm/test_tokenizer_metaspace_split.cpp`, metaspace.rs ports).
+- W1b/c library: `vllm::multimodal::ParakeetTranscriber`
+  (`parakeet_transcription.{h,cpp}`) absorbs WAV ingest
+  (`DecodeWavPcm16Mono`), model_type head dispatch and tokenizer decode; the
+  example's private `ReadWav16BitMono`/`LoadVocab`/`DecodeIds` are DELETED.
+- W2 registry: `ParakeetForCTC/ForRNNT/ForTDT` registered
+  (`parakeet_registry.cpp`), `ModelInfo` grows the SupportsTranscription
+  mirror (interfaces.py:1110-1118); BEYOND-PIN breadth recorded (pinned vLLM:
+  Parakeet = NemotronH audio component only, registry.py:511-513).
+  Refuse-by-task: every factory hook + `LoadedEngine::FromModelDir` (via new
+  non-throwing `PeekHfArchitectures`) refuse actionably; registry pins moved
+  30 -> 33.
+- W3 C ABI: `vllm_transcribe` + params/result structs, ABI v10 -> 11;
+  `vllm_engine_load` task-dispatches a transcription-only dir to the seam;
+  text entrypoints and `vllm_transcribe` refuse each other's handles cleanly.
+  FIRST real-checkpoint load gated through the public ABI (`test_capi` v11
+  cases close the audit's severity note). FEATURES abi-capability row flips
+  to reachable; `abi-capability-allowlist.txt` shrinks by the transcription
+  row.
+- W4 server: task-conditional `/v1/audio/transcriptions` (multipart `file`,
+  response_format json/text) through the SAME seam; serving-less `ApiServer`
+  ctor = vLLM's supported_tasks-conditional registration (generate routes 404
+  on an ASR server); `examples/server` dispatches by resolved arch; verified
+  LIVE with curl. Residuals: run_batch transcription line;
+  verbose_json/srt/vtt.
+- W5 example: `examples/parakeet_transcribe` = thin `vllm.h` client
+  (`vllm::shared`), stdout DIFF-IDENTICAL to the pre-fold binary on both
+  fixtures; `example-abi-allowlist.txt` loses its row;
+  `MAX_INTERNAL_REACHING` 12 -> 11 with the test pin + spec claims moved.
+
+**Gates.** Full CPU build clean (`-Werror`, 0 warnings); ctest 349/349 (345
+parallel + 4 serial; the only 2 reds were the registry count pins, moved as
+their comments instruct); surface guard + 46-case mutation suite green with
+the SHRINK enforced; every new test mutation-verified red/green (tokenizer
+decode rule + split gate, CTC collapse, transcription-only flag, ABI dispatch
++ input validation, server response_format + route gate).
+
+**Residuals (honest).** (1) run_batch `/v1/audio/transcriptions` stays a named
+residual (batch line shape carries no audio). (2) verbose_json/srt/vtt
+response formats -> 400 naming the residual. (3) A REAL pretrained checkpoint
+was not re-downloaded (safe defaults); the fold gate rests on the committed
+synthetic pair + the P4/P6 pretrained evidence. (4) A real Parakeet
+tokenizer.json may carry normalizer fields `FromHfJson` refuses loudly —
+untestable CPU-side without the checkpoint, fails loud not wrong. (5) Whisper/
+Voxtral remain off-registry (fold #9/#10 of the audit).

CMakeLists.txt

@@ -666,6 +666,13 @@ add_library(vllm STATIC
   src/vllm/model_executor/models/parakeet_transducer.cpp
   src/vllm/model_executor/models/parakeet_weights.cpp
   src/vllm/multimodal/parakeet_audio_processor.cpp
+  # The ONE transcription seam every consumer drives (C ABI vllm_transcribe,
+  # the server's /v1/audio/transcriptions, the parakeet-transcribe example) —
+  # ARCH-ONE-SURFACE ROW 1: absorbs the pipeline examples/parakeet_transcribe
+  # used to own privately. The refuse-by-task registry TU registers the three
+  # Parakeet head archs so config.json RESOLVES (SupportsTranscription mirror).
+  src/vllm/multimodal/parakeet_transcription.cpp
+  src/vllm/model_executor/models/parakeet_registry.cpp
   src/vllm/v1/core/encoder_cache_manager.cpp
   src/vllm/tokenizer/unicode_data.cpp
   src/vllm/tokenizer/pretokenizer.cpp

docs/BENCHMARKS.md

@@ -336,7 +336,7 @@ built on it rather than keeping the flattering one.
 | Vulkan vs llama.cpp Vulkan (`BENCH-VK-LLAMA`) | **NOT APPLICABLE: nothing measured, claimed or owed.** 16 NATIVE kernels; 71 on the host tier. opt-125m runs e2e token-exact on llvmpipe; no speed measured. [Detail](../.agents/specs/vulkan-full-support.md) | `VK-C` coopmat A/B on Thor (`VT_VULKAN_COOPMAT=0` A/Bs it): **11.1x-32.9x** vs our UNTILED scalar kernel, not vs a competent GEMM. `VK-E`: llama.cpp `-DGGML_VULKAN=ON` at `237ad9b96` on dgx, same GGUF, three columns |
 | ROCm (`BACKEND-GATE-ROCM-VLLM` / `-SGLANG`) | **NOT APPLICABLE: no number measured, claimed or owed.** The W0 skeleton registers 1 of 106 ops and its HIP sources have never been compiled by anyone; no AMD hardware here | A contributor's first `-DVLLM_CPP_HIP=ON` build ([#41](https://github.com/mudler/vllm.cpp/issues/41)). Only once a model runs does a same-box vLLM-ROCm oracle become the gate; the floor is vLLM, quant-matched |
 | SGLang floor arms | Never ran | Both arms of the SGLang comparison |
-| Parakeet/FastConformer ASR (kernels P1-P3 + encoder/CTC P4) | **NO number measured, claimed or owed.** Correctness-gated only, CPU f32; no CUDA provider, no GPU suite run, no aarch64 run. | Floor is `parakeet.cpp`, same clip and box; needs a CUDA provider and a pretrained checkpoint |
+| Parakeet/FastConformer ASR (P1-P4 + ONE-SURFACE fold ROW 1) | **NO number measured, claimed or owed.** Correctness-gated only, CPU f32; the 2026-08-07 surface fold (`vllm_transcribe`, `/v1/audio/transcriptions`) is transcript-byte-identical plumbing, no speed claim. | Floor is `parakeet.cpp`, same clip and box; needs a CUDA provider and a pretrained checkpoint |
 | cuBLAS invocation-parity guard | CI guard landed (CPU); `kGemvHeuristicAlgos` refactor build-verify owed | `nvcc` rebuild + SACRED gate on dgx |
 | Ampere consumer (`sm_86`, RTX 3090 class) | **No number owed; no such board here.** 2026-08-06 build-verify: 7/7 FA2 TUs 0-warn, real `sm_86` SASS. [Detail](../.agents/benchmark-record.md) | External RTX 3090 report. Floor is llama.cpp on that card (GGUF, not our Blackwell-only NVFP4 grid) |
 | Pre-Ampere breadth (Turing `sm_75` / Volta `sm_70` / Pascal) | **No number owed; nothing runs on these arches.** 2026-08-06 `sm_75`: 20/20 TUs PASS (0 err/warn), WMMA bodies + all 3 selectors arch-gated; GB10 SASS byte-identical. [Detail](../.agents/benchmark-record.md) | Full-library LINK at `sm_75` + `cuobjdump` SASS, then a build-supported row. The fp16 `fattn` port is speed-only now; its floor when a card exists is llama.cpp on that card |