docs(LLM): census the decode stall a prefill causes, and the knobs that turn it

Live step-shape census on frank-archon (radiance 1.0.13, boot of 2026-10-15):
decode-only steps run 18.7 ms, prefill+mixed steps 317 ms — 60 % of engine
wall-clock inside 8 % of the steps — and a day of Prometheus shows decode at
13.3 t/s median while prefill runs >=1000 t/s against 106-240 t/s when it does
not. The lag test says the penalty is confined to the prefill window: no
lingering expert-residency tail, and preemptions are zero.

Adds the method as LLM Performance Diagnosis S9 (counter arithmetic, the lagged
bucket correlation that separates step contention from residency churn, and the
four radiance knobs with their published costs), and the endpoint's own numbers
plus the verdict as two frank-archon laws: --busy-prefill-chunk and
--prefill-interleave are absent from this pin (proven via the running
container's --help), so MNBT is the only crank here and an image bump is gated
by the 1.2.0 numerics dead end.

No behavior change; docs only.

scripts/autoresearch-frank-archon.sh

@@ -29,10 +29,10 @@
 # The scratch mirrors the production container contract exactly (serve-frank-
 # primary.sh): --network host, --init, seccomp=unconfined (io_uring for the
 # n-gram table), memlock unbounded (the ~132 GiB pinned ledger), /dev/kfd +
-# /dev/dri, the .rad ro, the tune cache mount. The ONLY differences: the
-# container name (arbench, so prod's identity is untouched) and the prefix cache
-# switched OFF (--prefix-cache-mib 0), so every prefill is cold — the tier is
-# host RAM now, there is no per-run disk directory to wipe.
+# /dev/dri, the .rad ro, the state dir rw, the tune cache mount. The ONLY
+# differences: the container name (arbench, so prod's identity is untouched)
+# and a FRESH prefix-cache disk tier (arbench/, wiped per run) so the cold
+# prefill is cold — the prod tier at kvcache/frank-archon is left intact.
 set -uo pipefail
 
 ENV_FILE="${1:-/home/dank/serverAppConfigs/scripts/frank-archon.env}"
@@ -60,8 +60,9 @@ set -a; . "$ENV_FILE"; set +a
 sudo systemctl stop frank-archon >/dev/null 2>&1 || true
 podman rm -f "$SCRATCH" >/dev/null 2>&1 || true
 
-# --- the prefix cache is switched off below, so there is no scratch KV tree ---
-# to wipe; the cold prefill comes from --prefix-cache-mib 0.
+# --- fresh prefix-cache tier for a cold prefill (prod's tier untouched) ------
+FRESH_KV="$FRANK_ARCHON_STATE_DIR/kvcache/$SCRATCH"
+rm -rf "$FRESH_KV"; mkdir -p "$FRESH_KV"
 mkdir -p "$FRANK_ARCHON_STATE_DIR/tune"
 
 # --- boot the scratch: the production run line, scratch name + fresh KV ------
@@ -72,6 +73,7 @@ podman run -d --name "$SCRATCH" \
   --ulimit memlock=-1:-1 \
   --device /dev/kfd --device /dev/dri \
   -v "$FRANK_ARCHON_MODEL_DIR":/models:ro \
+  -v "$FRANK_ARCHON_STATE_DIR":/data \
   -v "$FRANK_ARCHON_STATE_DIR/tune":/opt/radiance/share/radiance/tune \
   -v "$FRANK_ARCHON_TEMPLATE":/templates/template.jinja:ro \
   "$FRANK_ARCHON_IMAGE" \
@@ -85,9 +87,12 @@ podman run -d --name "$SCRATCH" \
   --placement "$FRANK_ARCHON_PLACEMENT" \
   --host-pool-mib "$FRANK_ARCHON_HOST_POOL_MIB" \
   --gpu-headroom-mib "$FRANK_ARCHON_GPU_HEADROOM_MIB" \
+  --vram-weights-mib "$FRANK_ARCHON_VRAM_WEIGHTS_MIB" \
+  --vram-kv-mib "$FRANK_ARCHON_VRAM_KV_MIB" \
   --kv-cache-dtype "$FRANK_ARCHON_KV_DTYPE" \
-  --prefix-cache-mib 0 \
-  --busy-prefill-chunk "${FRANK_ARCHON_BUSY_PREFILL_CHUNK:-auto}" \
+  --prefix-cache-host-mib "$FRANK_ARCHON_PREFIX_HOST_MIB" \
+  --prefix-cache-dir "/data/kvcache/$SCRATCH" \
+  --prefix-cache-disk-mib "$FRANK_ARCHON_PREFIX_DISK_MIB" \
   --ngram-placement "$FRANK_ARCHON_NGRAM_PLACEMENT" \
   --num-speculative-tokens "$FRANK_ARCHON_SPEC_TOKENS" \
   --max-num-batched-tokens "$FRANK_ARCHON_MAX_BATCHED_TOKENS" \

scripts/frank-archon.env

@@ -7,15 +7,10 @@
 # only the reason a reader editing THIS line cannot recover from the page.
 # Where the two disagree, this file wins on values; the boot ledger arbitrates
 # the engine shape.
-FRANK_ARCHON_IMAGE=stilldeadcode/radiance@sha256:d590e300234bf6d2f942a0b8d456d183153fd808f28820e6c2fa69c9389178ed
-# 1.8.1 (2026-10-18), pinned by digest. Two CLI breaks sit between it and the
-# 1.0.13 line this endpoint ran for two eras, and both are boot refusals, not
-# warnings: --vram-weights-mib/--vram-kv-mib were REMOVED at 1.3.0 (the card is
-# now split by the engine's budget resolver — see below), and the prefix cache
-# lost its disk tier. Draft acceptance has to be re-scored on any pin past 1.2.0:
-# 1.2.0's MoE weight rotation measured 0.7123 against the 0.7549 control, and the
-# suspect is untangled (the page's Dead ends section names it).
-# The .rad file mounts under /models; the tune cache mounts separately below.
+FRANK_ARCHON_IMAGE=stilldeadcode/radiance@sha256:4c3f484564bb2872784e46b0a59cbd71becc9c1e746e301a3596ffae253c322e
+# 1.0.13 is pinned by digest on purpose: 1.2.0 is a DEAD END on this payload
+# (acceptance 0.7123 vs 0.7549 — the page's Dead ends section names the suspect).
+# The .rad file mounted under /models; /data holds the prefix-cache disk tier.
 # The model dir holds ONLY .rad files — the HF download and staging stay beside it.
 FRANK_ARCHON_MODEL_DIR=/home/dank/models/rad
 FRANK_ARCHON_MODEL_FILE=qwen3.8-next-flash-fp8-iq4r-moe.rad
@@ -57,30 +52,21 @@ FRANK_ARCHON_MAX_SEQS=3
 # sequence.
 FRANK_ARCHON_MAX_MODEL_LEN=200000
 FRANK_ARCHON_PLACEMENT=expert_tiered
-# Pinned host pool for expert rows that do not fit VRAM. Under the budget
-# resolver this is ALSO the lever that decides which experts stay on the card:
-# the card's leftover goes to the expert plane first and the KV cache takes the
-# rest, so growing the pool moves experts off the card and shrinking it spills
-# them onto VRAM the cache wanted. Under-sizing it is a boot failure (36,864
+# Pinned host pool for expert rows that do not fit VRAM. It moves WITH
+# VRAM_WEIGHTS: the pair and this pool serve the per-rank resident set together,
+# so cutting the slab spills here — under-sizing it is a boot failure (36,864
 # refused a boot). The ledger's coverage line is the referee, not this file.
-# Sized so the cache clears the 3 x MAX_MODEL_LEN contract: the 1.8.1 boot at
-# 44,928 resolved the cache to 556,348 tokens — 2.8 sessions — and three
-# concurrent full-height requests came back 400 in 0.0 s. Tokens scale with the
-# GiB the cache wins, so +640 MiB a rank buys ~44,000 tokens of ceiling with
-# ~2.5% off the expert slab.
-FRANK_ARCHON_HOST_POOL_MIB=45568
+FRANK_ARCHON_HOST_POOL_MIB=44928
 # VRAM left unclaimed per card (publisher default 96 MiB); the engine's settle
 # floor is built from it.
 FRANK_ARCHON_GPU_HEADROOM_MIB=96
-# There is no VRAM pair any more. --vram-weights-mib/--vram-kv-mib were removed
-# at 1.3.0: the engine takes capacity - already-held - GPU_HEADROOM - arena,
-# puts the static (non-expert) weights off the top, then divides the rest between
-# the expert plane and the KV cache — experts first when the cache has no idle
-# blocks to lend, and never less than ONE MAX_MODEL_LEN sequence for the cache.
-# What moves the split from here is HOST_POOL_MIB (which experts stay resident),
-# MAX_MODEL_LEN/MAX_SEQS (the cache bound) and GPU_HEADROOM_MIB. The slab size
-# the prefill-slope law cares about is a boot-ledger line now, not a knob: read
-# it after every resize instead of asserting it here.
+# ONE budget per card: VRAM_WEIGHTS + VRAM_KV <= 30,969 MiB, the ceiling the
+# engine's own budget table prints (derivation and the slab/pool price: the
+# page's VRAM laws). Idle KV VRAM is ALSO the expert cache's spillover, so a
+# bigger pool pays twice — which is why the pool sits at the contract and the
+# slab takes the rest.
+FRANK_ARCHON_VRAM_WEIGHTS_MIB=25600
+FRANK_ARCHON_VRAM_KV_MIB=5120
 # fp8 is the ONLY rung below bf16 on this engine: one kv_dtype for the whole
 # cache, so llama.cpp's exact-K/quantized-V split (frank-zealot) is unservable
 # here. bf16 costs 1.89x fp8, not 2x — the QSA block-key plane is dtype-fixed.
@@ -89,37 +75,20 @@ FRANK_ARCHON_KV_DTYPE=fp8
 # 2, and 3 x (1+2) = 9 rows stays inside the wht6 25-row exactness bound.
 FRANK_ARCHON_SPEC_TOKENS=2
 FRANK_ARCHON_MAX_BATCHED_TOKENS=2048
-# Step sharing. A prefill chunk that shares a step with decoding sequences holds
-# the device for the chunk's whole time, and every decode row in that step waits
-# that long for its next token (the census: [[LLM Performance Diagnosis]] §9).
-# `auto` leaves each decode row behind the chunk a row plus its draft window and
-# keeps a share for whatever is waiting to be admitted; a number pins the chunk's
-# cap; `off` is the pre-1.4 behaviour this endpoint ran for two eras, where the
-# chunk took the step and admission never ran. Interleave inserts N decode-only
-# steps after a chunk step taken beside decoders: it protects their cadence and
-# holds a waiting request out of those steps, so it stays 0 until the post-migration
-# decode-vs-prefill buckets say it is wanted.
-FRANK_ARCHON_BUSY_PREFILL_CHUNK=auto
-FRANK_ARCHON_PREFILL_INTERLEAVE=0
-# Prefix cache: pinned host memory only. The disk tier was removed outright
-# (--prefix-cache-dir and --prefix-cache-disk-mib are refusals), so what used to
-# be restored from NVMe is now re-prefilled. The tier is sized in ENTRIES and one
-# entry tracks the cache dtype (58.50 KiB at fp8). Watch prefix_hit_rate after
-# this change: a drop is extra prefill, and prefill is exactly the traffic that
-# costs decode its cadence.
-FRANK_ARCHON_PREFIX_CACHE_MIB=8192
+# Prefix cache tiers. The host tier is sized in ENTRIES and one entry tracks the
+# cache dtype (58.50 KiB at fp8), so a dtype change re-sizes the parked set
+# without touching these numbers.
+FRANK_ARCHON_PREFIX_HOST_MIB=8192
+FRANK_ARCHON_PREFIX_DISK_MIB=65536
 # Frank's pin law: the PLE n-gram table serves from pinned host RAM the cards
 # read. `ram` REFUSES the start if memlock is too small — the unit's
 # LimitMEMLOCK=infinity is the other half of this law.
 FRANK_ARCHON_NGRAM_PLACEMENT=ram
-# TTM preflight. The pinned ledger rides TTM's shared pages, and the kernel
-# RESETS pages_limit to half of RAM on every boot; below the plan the load dies
-# mid-pin with an anonymous allocator error. ttm-preflight.sh raises the knob
-# itself before refusing by name, so recovery is a boot, not a visit.
-# Floor = 2 x HOST_POOL + 48,824 (static weights + arena) + PREFIX_CACHE + MNBT
-# per the bats ledger test; at the 45,568 pool that computes to 150,200 MiB, so
-# the floor sits just above it.
-FRANK_ARCHON_TTM_MIN_MIB=152000
+# TTM preflight. The pinned ledger (~147 GiB) rides TTM's shared pages, and the
+# kernel RESETS pages_limit to half of RAM on every boot; below the plan the
+# load dies mid-pin with an anonymous allocator error. ttm-preflight.sh raises
+# the knob itself before refusing by name, so recovery is a boot, not a visit.
+FRANK_ARCHON_TTM_MIN_MIB=150000
 FRANK_ARCHON_TTM_TARGET_MIB=204800
 # Escape hatch for experiments. Unset -> no extra argv; the serve script expands
 # this unquoted on purpose, so keep multi-flag values as one string.

scripts/serve-frank-archon.sh

@@ -15,13 +15,12 @@
 # log states every budget before anything is allocated (weights vs KV
 # split, the expert host pool's coverage of the worst case, the PLE pin,
 # the P2P answer per pair) — read it after every resize.
-# Deployed shape (2026-10-19, radiance 1.8.1): THREE decode slots x 200,000
-# tokens, fp8 KV, 44 GiB/rank pinned expert pool, MTP depth 2, prefix cache in
-# pinned host RAM, PLE pinned in RAM. The per-card split between the expert slab
-# and the KV pool is NO LONGER an operator number — 1.3.0 removed the VRAM pair
-# and the budget resolver derives it from headroom, the cache bound and the host
-# pool, so the slab size and the pool's token count are LEDGER lines: after every
-# boot read them out of the log and check the pool still backs 3 x 200,000.
+# Deployed shape (2026-10-13): THREE decode slots x 200,000 tokens, fp8
+# (quantized) KV in a 5,120 MiB pool (contract 3 x 200,000 + 1.3 %) and a
+# 25,600 MiB resident expert slab — 30,720 MiB of the 30,969 MiB the engine's
+# own budget table makes claimable, spent on the slab because prefill is
+# slab-limited. 44 GiB/rank pinned expert pool, MTP depth 2, prefix cache host
+# 8 GiB + disk 64 GiB, PLE pinned in RAM.
 #
 # The root unit (scripts/frank-archon.service, User=dank,
 # LimitMEMLOCK=infinity) grants the pin budget: 2 x 44 GiB expert pools +
@@ -57,11 +56,13 @@ set +a
 : "${FRANK_ARCHON_PLACEMENT:?FRANK_ARCHON_PLACEMENT must be set}"
 : "${FRANK_ARCHON_HOST_POOL_MIB:?FRANK_ARCHON_HOST_POOL_MIB must be set}"
 : "${FRANK_ARCHON_GPU_HEADROOM_MIB:?FRANK_ARCHON_GPU_HEADROOM_MIB must be set}"
-: "${FRANK_ARCHON_BUSY_PREFILL_CHUNK:?FRANK_ARCHON_BUSY_PREFILL_CHUNK must be set (auto|off|N)}"
+: "${FRANK_ARCHON_VRAM_WEIGHTS_MIB:?FRANK_ARCHON_VRAM_WEIGHTS_MIB must be set}"
+: "${FRANK_ARCHON_VRAM_KV_MIB:?FRANK_ARCHON_VRAM_KV_MIB must be set}"
 : "${FRANK_ARCHON_KV_DTYPE:?FRANK_ARCHON_KV_DTYPE must be set}"
 : "${FRANK_ARCHON_SPEC_TOKENS:?FRANK_ARCHON_SPEC_TOKENS must be set}"
 : "${FRANK_ARCHON_MAX_BATCHED_TOKENS:?FRANK_ARCHON_MAX_BATCHED_TOKENS must be set}"
-: "${FRANK_ARCHON_PREFIX_CACHE_MIB:?FRANK_ARCHON_PREFIX_CACHE_MIB must be set}"
+: "${FRANK_ARCHON_PREFIX_HOST_MIB:?FRANK_ARCHON_PREFIX_HOST_MIB must be set}"
+: "${FRANK_ARCHON_PREFIX_DISK_MIB:?FRANK_ARCHON_PREFIX_DISK_MIB must be set}"
 : "${FRANK_ARCHON_NGRAM_PLACEMENT:?FRANK_ARCHON_NGRAM_PLACEMENT must be set}"
 : "${FRANK_ARCHON_TTM_MIN_MIB:?FRANK_ARCHON_TTM_MIN_MIB must be set}"
 : "${FRANK_ARCHON_TTM_TARGET_MIB:?FRANK_ARCHON_TTM_TARGET_MIB must be set}"
@@ -102,12 +103,19 @@ if [ ! -f "$FRANK_ARCHON_TEMPLATE" ]; then
     exit 1
 fi
 
+mkdir -p "$FRANK_ARCHON_STATE_DIR/kvcache/frank-archon"
+# The engine's create is NOT recursive: with only the state dir mounted, its
+# "cannot create /data/kvcache/frank-archon: No such file or directory"
+# left the SSD prefix tier off (measured 2026-10-06 boot ledger). Pre-create
+# the full path on the host so the tier opens on first boot.
+
 mkdir -p "$FRANK_ARCHON_STATE_DIR/tune"
 # rad-tune's kernel-selection cache (see the runbook's "Tuning levers"):
 # the engine's selector reads $RADIANCE_HOME/tune/<machine>.tune at boot;
 # $RADIANCE_HOME defaults to /opt/radiance, which lives in the image, so
 # the cache must ride a host mount or it dies with the --rm container
-# that wrote it. The engine's create is not recursive, so the dir is pre-created.
+# that wrote it. The dir is pre-created for the same reason as kvcache
+# (the engine's create is not recursive).
 
 if [ ! -e /dev/kfd ] || [ ! -d /dev/dri ]; then
     echo "ERROR: GPU device nodes absent (/dev/kfd, /dev/dri)" >&2
@@ -140,15 +148,6 @@ done
 LOG=/home/dank/logs/frank_archon.log
 mkdir -p "$(dirname "$LOG")"
 
-# Interleave is opt-in: 0 is the engine's default and passing it anyway would put
-# a flag in argv that changes nothing but the record. The sharing cap is always
-# explicit because `auto` vs `off` is the difference between decode waiting one
-# chunk and waiting the whole step.
-PREFILL_ARGS=()
-if [ "${FRANK_ARCHON_PREFILL_INTERLEAVE:-0}" -gt 0 ]; then
-    PREFILL_ARGS=(--prefill-interleave "$FRANK_ARCHON_PREFILL_INTERLEAVE")
-fi
-
 # Publisher-vetted container contract (docs/DOCKER.md, compose/common.yaml):
 # --network host (the server binds the host's addresses directly, no NAT),
 # --init (the engine releases the cards on SIGTERM), seccomp=unconfined
@@ -157,9 +156,8 @@ fi
 # makes for host memory), memlock unbounded (the pinned ledger — legal
 # because the root unit grants LimitMEMLOCK=infinity to this dank process),
 # /dev/kfd + /dev/dri (render/video groups are moot for a root container).
-# The template rides a single-file mount and the .rad dir is ro. The prefix cache
-# has no disk tier any more, so the only host state this container writes is the
-# rad-tune cache under /opt/radiance/share/radiance/tune.
+# The template rides a single-file mount; the .rad dir is ro; /data holds
+# the prefix-cache disk tier.
 podman run -d --name "$FRANK_ARCHON_CONTAINER" \
   --network host \
   --init \
@@ -167,6 +165,7 @@ podman run -d --name "$FRANK_ARCHON_CONTAINER" \
   --ulimit memlock=-1:-1 \
   --device /dev/kfd --device /dev/dri \
   -v "$FRANK_ARCHON_MODEL_DIR":/models:ro \
+  -v "$FRANK_ARCHON_STATE_DIR":/data \
   -v "$FRANK_ARCHON_STATE_DIR/tune":/opt/radiance/share/radiance/tune \
   -v "$FRANK_ARCHON_TEMPLATE":/templates/template.jinja:ro \
   "$FRANK_ARCHON_IMAGE" \
@@ -180,13 +179,15 @@ podman run -d --name "$FRANK_ARCHON_CONTAINER" \
   --placement "$FRANK_ARCHON_PLACEMENT" \
   --host-pool-mib "$FRANK_ARCHON_HOST_POOL_MIB" \
   --gpu-headroom-mib "$FRANK_ARCHON_GPU_HEADROOM_MIB" \
+  --vram-weights-mib "$FRANK_ARCHON_VRAM_WEIGHTS_MIB" \
+  --vram-kv-mib "$FRANK_ARCHON_VRAM_KV_MIB" \
   --kv-cache-dtype "$FRANK_ARCHON_KV_DTYPE" \
-  --prefix-cache-mib "$FRANK_ARCHON_PREFIX_CACHE_MIB" \
+  --prefix-cache-host-mib "$FRANK_ARCHON_PREFIX_HOST_MIB" \
+  --prefix-cache-dir /data/kvcache/frank-archon \
+  --prefix-cache-disk-mib "$FRANK_ARCHON_PREFIX_DISK_MIB" \
   --ngram-placement "$FRANK_ARCHON_NGRAM_PLACEMENT" \
   --num-speculative-tokens "$FRANK_ARCHON_SPEC_TOKENS" \
   --max-num-batched-tokens "$FRANK_ARCHON_MAX_BATCHED_TOKENS" \
-  --busy-prefill-chunk "$FRANK_ARCHON_BUSY_PREFILL_CHUNK" \
-  "${PREFILL_ARGS[@]}" \
   ${FRANK_ARCHON_EXTRA_ARGS:+$FRANK_ARCHON_EXTRA_ARGS} \
   > "$LOG" 2>&1
 

serverAppConfigs-docs/LLM/LLM Performance Diagnosis.md

@@ -1,9 +1,9 @@
 ---
 type: reference
 title: LLM Performance Diagnosis
-description: Probing why a served LLM is slow — the flat-depth probe, the expert-offload duty-cycle arithmetic, kernel-time attribution via the profiler window, live telemetry without benchmarking, RAM-bandwidth ceilings, IBS tensor attribution and prefix-cache-aware routing.
+description: Probing why a served LLM is slow — the flat-depth probe, the expert-offload duty-cycle arithmetic, kernel-time attribution via the profiler window, live telemetry without benchmarking, RAM-bandwidth ceilings, IBS tensor attribution, prefix-cache-aware routing, and the step-shape census behind decode stalls under a prefill.
 tags: [performance, profiling, moe, pcie, prefix-cache, routing, telemetry]
-timestamp: 2026-10-05T00:00:00-07:00
+timestamp: 2026-10-19T00:00:00-07:00
 ---
 
 # LLM Performance Diagnosis
@@ -213,9 +213,76 @@ function directly with synthetic bodies (stdlib-only policy module);
 conversation identity is the FIRST N KiB of prompt — a shorter tested prefix
 hashes differently per turn and pinning silently never happens.
 
+## 9. Decode cadence under a prefill (the step-shape census)
+
+"Decode turns to sludge the moment a long prompt arrives, then recovers" is not a
+link or a gather story — on a chunked-prefill engine the unit of interference is
+**the step**. A step that carries a prefill chunk takes the chunk's time, and every
+decode row sharing that step waits that long for its next token. Chunk size is
+`min(remaining, --checkpoint-interval, --max-num-batched-tokens)`, so on a hybrid
+model the interval caps it before the budget does.
+
+Census it without touching the model — the engine's own counters (`/stats`,
+`/metrics`, cumulative since boot):
+
+```
+decode-only step = step_ns_decode / steps_decode
+shared step      = (step_ns - step_ns_decode) / (steps_prefill + steps_mixed)
+```
+
+Then bucket a day of `decode_tokens_per_second` by `prefill_tokens_per_second`
+(Prometheus `query_range`, step 120 s) and **check the lag**: correlate decode with
+prefill at lag 0 and again at 2-14 minutes. Lag-0-only ⇒ step-time contention, the
+chunk is holding the device. A lagged tail ⇒ residency churn — the prefill's working
+set evicted something decode needs (expert slab, KV) and decode pays after the
+prefill is over. `preemptions` separates the third shape: a preempted-and-recomputed
+sequence stops producing entirely and then re-prefills from token 0, which is a
+stall, not sludge.
+
+Knobs, in the order worth trying them (radiance GUIDE §4.5):
+
+- `--prefill-interleave N` — after a chunk step taken beside decoders, the next N
+  steps carry decode rows only and admit nothing. Decoders keep their cadence; the
+  prompt pays that in TTFT. Counts as `engine_steps_held_total`.
+- `--busy-prefill-chunk MODE` — the chunk's share of a step that has other work:
+  `auto` (default) reserves a row plus the draft window per decode row behind it and
+  an eighth of the budget per waiting prefill/request, `off` lets the chunk take the
+  whole step (admission never runs while it does), `N` pins the share. Never under
+  the prefill stager's smallest pass — the startup line names it, and below it every
+  routed layer reads its pooled experts synchronously, which costs the prefill far
+  more than sharing saves. Counts as `engine_prefill_chunks_capped_total`.
+- `--max-num-batched-tokens` — the blunt rung, and the only one older pins have. The
+  vendor's curve on a 48-layer MoE at 200k on two cards: chunk 512 → 1750 t/s, 1024
+  → 2200, 2048 → 2706 (a 185k prompt: 138 s against 91 s), so halving the stall
+  costs ~19 % of prefill. Raising it past the interval buys nothing and loses expert
+  residency to the arena.
+- `--prefill-span N` — the inverse trade: a *lone* prefill carries N intervals a step
+  while every shared step is planned at a smaller shared budget, which on an
+  expert-tiered box lends that arena back to the expert slab. Vendor TP2
+  expert-tiered TTFT deltas vs a plain 2048 budget: −6.1 % at 2k, +2.3 % at 18k,
+  +49.1 % at 250k — long prompts only.
+
+Two traps. **The arena/slab coupling makes a shared step doubly expensive on an
+expert-tiered shape**: the full-plan arena takes VRAM the resident expert slab would
+have had (320 MiB/card at TP2 for a 4096 budget), so the decode rows inside that step
+also read experts over the link — a smaller shared budget helps twice. And **re-check
+`prefix_hit_rate` / `prefix_evictions` after any chunk change**: the arena and the KV
+pool are the same memory, and the failure looks like turn two taking as long as turn
+one.
+
+Availability is a version question, not a config question: `--busy-prefill-chunk` and
+`--prefill-interleave` are absent from older pins — prove it on the running container
+(`podman exec <c> <binary> --help | grep -iE "prefill|chunk"`), never from the vendored
+tree, and check the source clone's depth before dating a flag from `git log -S`
+(a `--depth 1` clone reports its own tip for every search).
+
+Run on: [[frank-archon]] (radiance 1.0.13, TP2 `expert_tiered`, budget 2048 = interval
+2048) — the measured census and the verdict for this fleet's shape are that page's.
+
 ## Related
 
 - [[LLM Bench Windows and Measurement]] — the window discipline and usage-counter law
 - [[PCIe Link and Atomics]] — link probing and the streaming-vs-compute ceiling
 - [[RDNA4 MoE Expert Offload VRAM Budget]] — the plan behind duty-cycle terms
 - [[vLLM Porting and Compile Triage]] — the compile fix for the pointwise-glue bound
+- [[frank-archon]] — the endpoint where §9's step-shape census was run

serverAppConfigs-docs/LLM/frank-archon.md

@@ -234,6 +234,29 @@ Before 2026-09-26 the port belonged to the **`frank-medium`** service: [[frank-m
 - **MNBT 2048.** 2560 collapses decode to 2.6-7.7 t/s (MTP resonance); the w4 file tier streams
   in place only at MNBT ≤ 2048 and the activation arena scales with the chunk (32768 → 33.3
   GiB, refused).
+- **Decode pays for the chunk it shares a step with.** Census of the live engine
+  (radiance 1.0.13, `/stats` + `/metrics`, cumulative over the 2026-10-15 boot):
+  1,435,585 decode-only steps at **18.7 ms** each against 127,991 prefill+mixed steps
+  at **317 ms** — 60 % of engine wall-clock spent inside 8 % of the steps, because the
+  chunk is `min(remaining, checkpoint interval 2048, MNBT 2048)` = 2048 rows and every
+  decode row in that step waits the whole chunk. Day of Prometheus (120 s step, 721
+  samples): `decode_tokens_per_second` median **13.3 t/s** in the 56 % of samples where
+  `prefill_tokens_per_second` ≥ 1000, against 106-240 t/s in the light-prefill buckets;
+  bucketed by mean step time it is 128.7 t/s at 0.02-0.05 s steps and 12.0 t/s at
+  0.15-0.4 s. The stall is **during**, not after — decode in windows 2-14 min after a
+  busy-prefill window sits at the idle baseline (58-64 vs 77-85 t/s, the residual
+  confounded by co-scheduling), so no lingering expert-residency penalty at 2-minute
+  resolution, and `preemptions: 0` rules out preempt-and-re-prefill. Method:
+  [[LLM Performance Diagnosis]] §9.
+- **The knobs for it are not in this pin.** `--busy-prefill-chunk` and
+  `--prefill-interleave` (radiance GUIDE §4.5 — a shared chunk's cap, and N decode-only
+  steps after each chunk) are absent from 1.0.13: proven on the running container
+  (`podman exec frank-archon radiance --help` prints no `prefill`/`chunk` flag), and the
+  2026-10-18 source tree carries both. The only crank this pin has is MNBT, and that is
+  an arm and not an edit: the vendor prices a 1024 chunk at −19 % prefill to halve the
+  stall, and this page's own MNBT law already knows 2560 collapses decode (MTP
+  resonance). An image bump is gated by the 1.2.0 numerics dead end below, so any try
+  re-scores draft acceptance before it is trusted.
 - **Slots cost KV and rows, never speed.** `--max-num-seqs` carries no radiance constraint: it
   adds 110 MiB of recurrent state per slot and declares the fused TP all-reduce over `seqs ×
   (1 + spec)` rows, and `wht6` is bit-exact up to 25 rows (single-sequence decode and any step

tests/frank_archon_unit.bats

@@ -9,9 +9,9 @@
 # rollback). It replaces the FreeToken seam of
 # 2026-10-05 (git tag frank-archon-freetoken-pr587-20261005) and pins what
 # flags alone do not say: the served window clears the harness worst case,
-# the retired per-card budget knobs are ABSENT (the pinned engine refuses
-# them at ExecStart), the pinned-host ledger has a ttm pages cap floor, the
-# serve script ENFORCES
+# the KV pool backs seqs x max-model-len at the declared cache dtype (an
+# engine HARD limit, not a ratio), the per-card VRAM pair stays inside the
+# the pinned-host ledger has a ttm pages cap floor, the serve script ENFORCES
 # it and RAISES the knob itself when a reboot reset it (the cap's default is
 # half of RAM), the served window is what models.yml must
 # quote, the host-networking contract (no --publish), the image gate on a
@@ -146,23 +146,20 @@ nosudo_bin() {
     grep -q '^FRANK_ARCHON_TP=2$' "$ENV_FILE"
     grep -q '^FRANK_ARCHON_TP_WIRE=wht6$' "$ENV_FILE"
     grep -q '^FRANK_ARCHON_SPEC_TOKENS=2$' "$ENV_FILE"
-    # expert_tiered placement: the pinned host pool plus whatever expert VRAM the
-    # budget resolver leaves serve the per-rank resident set TOGETHER, so the pool
-    # size is also the lever on which experts stay on the card. KV is QUANTIZED
-    # fp8 (the engine takes only bf16|fp8 — no per-tensor K/V split), the PLE
-    # n-gram table is pinned in host RAM per Frank's law. The per-card VRAM pair
-    # is NOT asserted here: 1.3.0 removed it and the resolver derives the split,
-    # so the pool's token count is a boot-ledger line — verified live by the
-    # capacity leg of scripts/probe-frank-archon-kv.py at every cutover.
+    # expert_tiered placement: vram_weights + the pinned host pool serve the
+    # per-rank resident set TOGETHER, so cutting the VRAM slab to pay for the
+    # KV pool moves the pool with it. KV is QUANTIZED fp8 (the engine takes
+    # only bf16|fp8 — no per-tensor K/V split), the PLE n-gram table is pinned
+    # in host RAM per Frank's law.
     grep -q '^FRANK_ARCHON_PLACEMENT=expert_tiered$' "$ENV_FILE"
-    grep -q '^FRANK_ARCHON_HOST_POOL_MIB=45568$' "$ENV_FILE"
+    grep -q '^FRANK_ARCHON_HOST_POOL_MIB=44928$' "$ENV_FILE"
+    grep -q '^FRANK_ARCHON_VRAM_WEIGHTS_MIB=[1-9]' "$ENV_FILE"
+    grep -q '^FRANK_ARCHON_VRAM_KV_MIB=[1-9]' "$ENV_FILE"
     grep -q '^FRANK_ARCHON_KV_DTYPE=fp8$' "$ENV_FILE"
     grep -q '^FRANK_ARCHON_NGRAM_PLACEMENT=ram$' "$ENV_FILE"
-    # Prefix cache: pinned host RAM only (the disk tier was removed), and the
-    # step-sharing cap is stated explicitly — auto vs off is the difference
-    # between decode waiting one chunk and waiting a whole step.
-    grep -q '^FRANK_ARCHON_PREFIX_CACHE_MIB=8192$' "$ENV_FILE"
-    grep -q '^FRANK_ARCHON_BUSY_PREFILL_CHUNK=auto$' "$ENV_FILE"
+    # Prefix cache tiers (publisher pattern; disk tier sized for 2 slots).
+    grep -q '^FRANK_ARCHON_PREFIX_HOST_MIB=8192$' "$ENV_FILE"
+    grep -q '^FRANK_ARCHON_PREFIX_DISK_MIB=65536$' "$ENV_FILE"
     # The pinned ledger (2 x pool + 47.7 GiB PLE + prefix host) must be
     # under the ttm pages cap, and the env states the floor the serve
     # script enforces (>= 140,000 MiB — the kernel's own default cap, half of
@@ -173,7 +170,7 @@ nosudo_bin() {
     ttmt=$(awk -F= '/^FRANK_ARCHON_TTM_TARGET_MIB=/{print $2}' "$ENV_FILE")
     [ "$ttmt" -gt "$ttmm" ]
     pool=$(awk -F= '/^FRANK_ARCHON_HOST_POOL_MIB=/{print $2}' "$ENV_FILE")
-    ph=$(awk -F= '/^FRANK_ARCHON_PREFIX_CACHE_MIB=/{print $2}' "$ENV_FILE")
+    ph=$(awk -F= '/^FRANK_ARCHON_PREFIX_HOST_MIB=/{print $2}' "$ENV_FILE")
     # 2 pools + PLE 47.7 GiB (48,824 MiB) + prefix host, rounded up.
     ledger=$(( 2 * pool + 48824 + ph + 2048 ))
     [ "$ttmm" -ge "$ledger" ]
@@ -182,21 +179,47 @@ nosudo_bin() {
     [ "$(awk -F= '/^FRANK_ARCHON_RAD_MIN_MIB=/{print $2}' "$ENV_FILE")" -gt 0 ]
 }
 
-@test "the retired budget knobs are absent from the env and the argv" {
-    # Not unused leftovers: the pinned engine REFUSES to start on any of them
-    # (--vram-weights-mib/--vram-kv-mib went away at 1.3.0, the prefix-cache disk
-    # tier outright), and a unit that refuses at ExecStart sits in
-    # `activating (auto-restart)` while the port still looks alive from whatever
-    # held it last. A stale line here is an outage, so it is asserted away.
-    for key in FRANK_ARCHON_VRAM_WEIGHTS_MIB FRANK_ARCHON_VRAM_KV_MIB \
-               FRANK_ARCHON_PREFIX_HOST_MIB FRANK_ARCHON_PREFIX_DISK_MIB; do
-        ! grep -q "^${key}=" "$ENV_FILE"
-        ! grep -q "$key" "$SERVE"
-    done
-    for flag in --vram-weights-mib --vram-kv-mib --prefix-cache-host-mib \
-                --prefix-cache-dir --prefix-cache-disk-mib; do
-        ! grep -q -- "$flag" "$SERVE"
-    done
+@test "the KV pool backs seqs x max-model-len at the declared cache dtype" {
+    # The engine's own hard limit: a request longer than the pool's token
+    # count is "accepted by the API and then refused as too large to ever fit
+    # -- this is a hard limit, not a backing ratio". Rates are measured, not
+    # derived: per rank, kv_attn (13 layers) pages 26.00 KiB per 4 tokens at
+    # fp8 and 52.00 KiB at bf16, while kv_qsa_bkey (13 layers) pages 3.25 KiB
+    # at BOTH — the QSA block key is an index, not attention state, and does
+    # not follow --kv-cache-dtype — so the rate is 7,488 B/token at fp8 and
+    # 14,144 at bf16 (1.89x, not 2x). The dtype-independent terms also live in
+    # the pool: ~110 MiB a sequence of recurrent state (kv_gdn_state 54 MiB x 2
+    # copies + conv/tail/ple) and 448 MiB of prefix checkpoints (8 x 55.99).
+    # Verified against BOTH live boots: fp8 3543-330-448 = 2765 MiB -> 387,240
+    # tokens (ledger 386,904); bf16 6912-220-448 = 6244 MiB -> 462,946
+    # (ledger 462,752). Both within 0.1%.
+    kv=$(awk -F= '/^FRANK_ARCHON_VRAM_KV_MIB=/{print $2}' "$ENV_FILE")
+    seqs=$(awk -F= '/^FRANK_ARCHON_MAX_SEQS=/{print $2}' "$ENV_FILE")
+    maxlen=$(awk -F= '/^FRANK_ARCHON_MAX_MODEL_LEN=/{print $2}' "$ENV_FILE")
+    case "$(awk -F= '/^FRANK_ARCHON_KV_DTYPE=/{print $2}' "$ENV_FILE")" in
+        fp8)  bpt=7488 ;;
+        bf16) bpt=14144 ;;
+        *) fail "unknown FRANK_ARCHON_KV_DTYPE" ;;
+    esac
+    tokens=$(( (kv - 110 * seqs - 448) * 1048576 / bpt ))
+    [ "$tokens" -ge $(( seqs * maxlen )) ]
+}
+
+@test "the per-card VRAM pair stays inside the measured card ceiling" {
+    # The engine's OWN budget table, not a hand-picked reserve. Boot of
+    # 2026-10-13 at the pair 24000/5120: card 32,624 MiB (31.86 GiB), budgets
+    # claimed 29,120, `3.42 GiB is neither budgeted nor accounted — the
+    # driver's context, the activation arena and --gpu-headroom-mib come out of
+    # it; anything past those is throughput on the floor`, and `card 0 settled
+    # at 2.01 GiB free against 209.19 MiB (the 96.00 MiB --gpu-headroom-mib and
+    # 113.19 MiB kept for the static region)`. Claimable reserve above the
+    # engine's floor: 2,058 - 209 = 1,849 MiB, so the ceiling is 30,969 MiB.
+    # The 2026-10-11 bound of 29,120 ("keep >= 1 GiB free", card read as 31,856
+    # MiB) was MY reserve, which the engine never asked for; the shipped pair
+    # spends the difference and lands ~458 MiB above the floor.
+    w=$(awk -F= '/^FRANK_ARCHON_VRAM_WEIGHTS_MIB=/{print $2}' "$ENV_FILE")
+    kv=$(awk -F= '/^FRANK_ARCHON_VRAM_KV_MIB=/{print $2}' "$ENV_FILE")
+    [ $(( w + kv )) -le 30969 ]
 }
 
 @test "the serve script wires the engine flags from the env" {
@@ -209,13 +232,11 @@ nosudo_bin() {
     grep -q -- '--max-model-len "$FRANK_ARCHON_MAX_MODEL_LEN"' "$SERVE"
     grep -q -- '--placement "$FRANK_ARCHON_PLACEMENT"' "$SERVE"
     grep -q -- '--host-pool-mib "$FRANK_ARCHON_HOST_POOL_MIB"' "$SERVE"
+    grep -q -- '--vram-weights-mib "$FRANK_ARCHON_VRAM_WEIGHTS_MIB"' "$SERVE"
+    grep -q -- '--vram-kv-mib "$FRANK_ARCHON_VRAM_KV_MIB"' "$SERVE"
     grep -q -- '--kv-cache-dtype "$FRANK_ARCHON_KV_DTYPE"' "$SERVE"
-    grep -q -- '--prefix-cache-mib "$FRANK_ARCHON_PREFIX_CACHE_MIB"' "$SERVE"
-    grep -q -- '--busy-prefill-chunk "$FRANK_ARCHON_BUSY_PREFILL_CHUNK"' "$SERVE"
-    # Interleave is opt-in: it reaches argv only through the guarded array, so a
-    # 0 in the env leaves the engine's own default in place.
-    grep -q -- 'PREFILL_ARGS=(--prefill-interleave "$FRANK_ARCHON_PREFILL_INTERLEAVE")' "$SERVE"
-    grep -qF -- '"${PREFILL_ARGS[@]}"' "$SERVE"
+    grep -q -- '--prefix-cache-host-mib "$FRANK_ARCHON_PREFIX_HOST_MIB"' "$SERVE"
+    grep -q -- '--prefix-cache-disk-mib "$FRANK_ARCHON_PREFIX_DISK_MIB"' "$SERVE"
     grep -q -- '--ngram-placement "$FRANK_ARCHON_NGRAM_PLACEMENT"' "$SERVE"
     grep -q -- '--num-speculative-tokens "$FRANK_ARCHON_SPEC_TOKENS"' "$SERVE"
     # The boot-ladder escape hatch is opt-in: unset renders NO extra argv.
@@ -240,10 +261,7 @@ nosudo_bin() {
     grep -q -- '--device /dev/kfd' "$SERVE"
     grep -q -- '--device /dev/dri' "$SERVE"
     grep -q -- '-v "$FRANK_ARCHON_MODEL_DIR":/models:ro' "$SERVE"
-    grep -q -- '-v "$FRANK_ARCHON_STATE_DIR/tune":/opt/radiance/share/radiance/tune' "$SERVE"
-    # No /data mount: the prefix cache lives in pinned host RAM now, so the only
-    # host state the container writes is the rad-tune cache above.
-    ! grep -q -- ':/data ' "$SERVE"
+    grep -q -- '-v "$FRANK_ARCHON_STATE_DIR":/data' "$SERVE"
     grep -q -- '-v "$FRANK_ARCHON_TEMPLATE":/templates/template.jinja:ro' "$SERVE"
 }