docs(core): retire pooled paged-attention decode to library-only API

[inureyes]

Summary

Resolves the PR #709 review finding that paged_decode_attention_pooled has no mlxcel-server caller. The decision recorded here is to retire the pooled decode entry point (and its select_pooled_paged_dispatch selector) to a library-only API rather than wire it into the scheduler decode.

Why retire (occupancy evidence, Apple M1 Ultra)

The fused kernel's winning island is single-slab only. A slab is POOL_SLAB_BLOCKS = 32 block rows (src/lib/mlxcel-core/src/cache/paged.rs) and a block holds DEFAULT_PAGED_BLOCK_SIZE = 32 tokens (src/server/batch/scheduler.rs), so one slab is 32 x 32 = 1024 token rows per layer across every sequence resident in the shared pool (PagedBlockPool::slab_count returns the layer's whole slab-list length). The selector requires slab_count <= 1 and batch_size >= 4, so the pool stays native only while B * ceil(len / 32) <= 32. At the shipped --parallel 4 default (#714, n_parallel = 4) that is len <= 256 total tokens per sequence, counting prompt, chat template, and generated tokens.

That island is negligible in production. The #714 serving-throughput bench drives 512-token prompts, which at B = 4 need 4 x 16 = 64 block rows = 2 slabs, so every layer is multi-slab from the first decode step (the #331 bench table in ADR 0001 shows every B >= 4 row at ctx >= 512 reading declined). The pool only appends slabs (#235: existing slabs are never freed), so a request that starts inside the island leaves it permanently within its first few dozen generated tokens. Wiring the pooled path in would thread a new batched-decode arm through every transformer family (high blast radius, jitter-class parity risk) for that transient sliver. Since the pooled path has no server caller, its measured production occupancy is definitionally zero today, so the closed-form geometry is stronger evidence than a thermally-noisy instrumented run.

What changed

• src/lib/mlxcel-core/src/layers.rs: library-only doc comments on paged_decode_attention_pooled, select_pooled_paged_dispatch, the MLXCEL_PAGED_ATTENTION_NATIVE override (NativePagedOverride), and the per-shape dispatch memo (PagedDispatchCache), stating they are not on the mlxcel-server decode path and are kept for external mlxcel-core consumers and examples/paged_attention_kernel_bench.rs.
• docs/adr/0001-paged-attention-gather-vs-fused-kernel.md: new decision record with the occupancy derivation, the geometry math, the chosen exit, and what would reopen the question.
• docs/environment-variables.md, docs/turbo-kv-cache.md: MLXCEL_PAGED_ATTENTION_NATIVE is now described as a library-consumer control and A/B pin for the bench, not a server knob.

What was kept vs removed

• Kept: the fused kernel (PagedBlockPool::paged_decode_fused), the selector, the memo, the env override, and examples/paged_attention_kernel_bench.rs (tested, benchmarked library surface).
• Kept: use_native_paged_kernel scheduler request. It also gates the live paged_decode_attention_dense_compat block-table decode path (src/models/llama3.rs and the other families), so it is shared plumbing, not dead code. No plumbing was removed.
• Removed: nothing. The pooled function, selector, kernel, and bench all remain.

Test plan

• cargo fmt --all -- --check
• cargo check --lib --tests --features metal,accelerate
• cargo clippy --lib --tests --features metal,accelerate -- -D warnings
• cargo test --release --features metal,accelerate -p mlxcel-core layers::tests:: (53 passed: selector island, boundaries, override pinning)
• cargo test --release --features metal,accelerate -p mlxcel-core ffi_tests::test_fused_paged_decode (2 passed: gather parity over 200 steps, GQA + batched)

Hardware: Apple M1 Ultra.

Closes #710