prefill: STRATA_PREFILL_ROUTED_STREAM=1 names the reason once when a streamed chunk keeps the default walk; test

With the switch set, a streamed chunk keeps the default issuer with STRATA_PREFILL_ISSUER=0, on the peer prompt ring,
and with STRATA_PREFILL_COPY_EVENT_EVERY > 1 or STRATA_PREFILL_COPY_WAIT_DEDUPE=1. That was silent, so a set switch read
as active where it could not run. The engine now prints one line with the reason (routed_stream::held_off) the first
time a streamed chunk is held off. Chunks below the stream floor print nothing, and with the switch unset nothing new
runs. routed_stream_test checks that a reason is given exactly when the walk is held off and that it names the setting.

docs/DETAILS.md

@@ -1066,17 +1066,19 @@ measured. "Exact" means the 10-prompt and 4K/20K identity gate with the switch o
 `STRATA_DEQUANT_WIDE` (wide dequantization of Q4_K, Q5_K, Q6_K and IQ4_XS for the prompt's dense weights) is on by default on
 sm_86 and sm_61, bit-exact. `STRATA_DEQUANT_WIDE=0` turns it off.
 
-`STRATA_PREFILL_ROUTED_STREAM=1` (opt-in; the streamed prompt walk of a chunk of 1,024 tokens or more, one GPU, the issuer
-thread): the issuer keeps at most `STRATA_PREFILL_ROUTED_STREAM_DEPTH` copies (default 16) queued ahead of the PCIe link,
-each layer's routing is handed to it as soon as the layer's router has run, and an expert not yet copied that no token of
-the chunk routes to is not copied at all. The routed experts go into the same ring slots as without the switch, so the
-prompt's results are the same bits, and the slots the prompt borrowed are refilled from RAM as before. With `STRATA_TRACE=1`
-each chunk prints how many ring entries it copied and how many it dropped. With `STRATA_PREFILL_COPY_EVENT_EVERY` above 1 or
-`STRATA_PREFILL_COPY_WAIT_DEDUPE=1` the switch stays off: those keep the default issuer, whose copy records the routed walk
-does not write. On an RTX 3090 (PCIe 3.0 x16, 250 W) with the Swift IQ3_XXS pack at the v0.2.6 release defaults, 23% fewer
-experts were streamed for a 2K prompt and 4% fewer at 32K (8,192-token chunks); a 1,790-token follow-up read on an
-18.8K-token conversation took 18% less time and fresh 2K, 4K and 32K reads ran 20%, 8% and 5% faster (4 pairs), with
-byte-identical replies in a deterministic lane at 1K to 32K.
+`STRATA_PREFILL_ROUTED_STREAM=1` (opt-in; the streamed prompt walk of a chunk of 1,024 tokens or more, one GPU, the
+issuer thread): the issuer keeps at most `STRATA_PREFILL_ROUTED_STREAM_DEPTH` copies (default 16) queued ahead of the
+PCIe link, each layer's routing is handed to it as soon as the layer's router has run, and an expert not yet copied that
+no token of the chunk routes to is not copied at all. The routed experts go into the same ring slots as without the
+switch, so the prompt's results are the same bits, and the slots the prompt borrowed are refilled from RAM as before.
+With `STRATA_TRACE=1` each chunk prints how many ring entries it copied and how many it dropped. With
+`STRATA_PREFILL_COPY_EVENT_EVERY` above 1 or `STRATA_PREFILL_COPY_WAIT_DEDUPE=1` the switch stays off: those keep the
+default issuer, whose copy records the routed walk does not write. When the switch is set but a streamed chunk keeps the
+default walk (these two, `STRATA_PREFILL_ISSUER=0` or the peer prompt ring), the engine prints the reason once. On an
+RTX 3090 (PCIe 3.0 x16, 250 W) with the Swift IQ3_XXS pack at the v0.2.6 release defaults, 23% fewer experts were
+streamed for a 2K prompt and 4% fewer at 32K (8,192-token chunks); a 1,790-token follow-up read on an 18.8K-token
+conversation took 18% less time and fresh 2K, 4K and 32K reads ran 20%, 8% and 5% faster (4 pairs), with byte-identical
+replies in a deterministic lane at 1K to 32K.
 
 ### RTX 20 (Turing, sm_75) kernels (opt-in)
 

include/strata/prefill/routed_stream.hpp

@@ -43,8 +43,18 @@ inline int depth_from(const char* v) {
 // not publish the entries a sparse consumer waits on (STRATA_PREFILL_COPY_EVENT_EVERY > 1: a_rec / rec_of) and does not
 // deduplicate release waits (STRATA_PREFILL_COPY_WAIT_DEDUPE=1).  With either set the chunk keeps the default issuer:
 // otherwise the consumer would wait on a record that never comes, or the requested wait policy would be bypassed.
+// held_off: why a streamed chunk keeps the default walk with the switch set (null when it takes the routed walk); the
+// engine prints it once, so a set switch does not read as active where it cannot run.
+inline const char* held_off(bool issuer_on, bool peer, int copy_event_every, bool copy_wait_dedupe) {
+    if (!issuer_on) return "the inline issuer (STRATA_PREFILL_ISSUER=0) copies every expert";
+    if (peer) return "the peer prompt ring (--peer-device) keeps its own walk";
+    if (copy_event_every != 1 || copy_wait_dedupe)
+        return "STRATA_PREFILL_COPY_EVENT_EVERY > 1 and STRATA_PREFILL_COPY_WAIT_DEDUPE=1 keep the default issuer, whose "
+               "copy records the routed walk does not write";
+    return nullptr;
+}
 inline bool eligible(bool stream_all, bool issuer_on, bool peer, int copy_event_every, bool copy_wait_dedupe) {
-    return stream_all && issuer_on && !peer && copy_event_every == 1 && !copy_wait_dedupe;
+    return stream_all && held_off(issuer_on, peer, copy_event_every, copy_wait_dedupe) == nullptr;
 }
 
 // Which experts each layer's tokens route to, published by the compute thread once the layer's router has run and

src/prefill/prefill.cpp

@@ -3489,6 +3489,12 @@ bool Prefill::run_impl(const int64_t* tokens, int64_t n, int64_t pos0, std::stri
                 std::fprintf(stderr, "strata: STRATA_PREFILL_ROUTED_STREAM=1: a streamed prompt chunk drops the experts no token "
                                      "routes to before they are copied (at most %d copies queued ahead of the link)\n", rs_depth);
             }
+        } else if (rs_env && stream_all) {
+            if (static bool said_off = false; !said_off) {
+                said_off = true;
+                std::fprintf(stderr, "strata: STRATA_PREFILL_ROUTED_STREAM=1 is not used: %s\n",
+                             routed_stream::held_off(issuer_on, m.pp != nullptr, copy_event_every, copy_wait_dedupe));
+            }
         }
         std::atomic<size_t> a_issued{0}, a_consumed{0};
         std::atomic<bool> a_stop{false};

tests/prefill/routed_stream_test.cpp

@@ -6,6 +6,7 @@
 
 #include <atomic>
 #include <cstdio>
+#include <cstring>
 #include <deque>
 #include <mutex>
 #include <random>
@@ -302,6 +303,21 @@ int main() {
         expect(!rs::eligible(true, true, false, every, true), "sparse events and dedupe: default walk");
     }
     expect(!rs::eligible(true, true, false, 1, true), "release-wait dedupe: default walk");
+    // the reason the engine prints once when the switch is set and a streamed chunk keeps the default walk
+    expect(rs::held_off(true, false, 1, false) == nullptr, "eligible: no reason");
+    for (bool iss : {false, true})
+        for (bool peer : {false, true})
+            for (int every : {1, 2, 16})
+                for (bool dedupe : {false, true}) {
+                    const char* why = rs::held_off(iss, peer, every, dedupe);
+                    expect((why == nullptr) == rs::eligible(true, iss, peer, every, dedupe), "a reason exactly when held off");
+                }
+    auto names = [](const char* why, const char* what) { return why != nullptr && std::strstr(why, what) != nullptr; };
+    expect(names(rs::held_off(false, false, 1, false), "STRATA_PREFILL_ISSUER=0"), "inline issuer named");
+    expect(names(rs::held_off(true, true, 1, false), "--peer-device"), "peer ring named");
+    expect(names(rs::held_off(true, false, 4, false), "STRATA_PREFILL_COPY_EVENT_EVERY") &&
+               names(rs::held_off(true, false, 1, true), "STRATA_PREFILL_COPY_WAIT_DEDUPE"),
+           "copy policies named");
 
     // the gate
     {