diag(quic): writer-side per-drain stats behind DEBUG=1 build flag

The qlog confirmed the writer emits 1 STREAM frame per packet on the
live wire, while MultiplexingCoalescingTest + MultiplexingAioquicTpsTest
both show ~9 streams per packet under synchronous drain. So the bug is
in the live driver flow — concurrent send loop + parser feed +
real-socket interleaving — and not in buildApplicationPacket itself.

To localize: add an opt-in trace at the END of buildApplicationPacket
that dumps per-drain state when QUIC_INTEROP_DEBUG=1:
  [writer.app] frames=N stream_frames=K streamsView=M active=A
               packetBudget_remaining=R connBudget_initial=C

  - frames vs stream_frames tells us if non-stream frames (ACK,
    MAX_DATA, MAX_STREAM_DATA) are bloating the packet
  - active vs streamsView tells us if isClosed filter dropped streams
  - packetBudget_remaining tells us if we hit the 64-byte break early
  - connBudget_initial tells us if conn flow control was zero

Wired three pieces:

  1. WriterDebug.kt — a single @Volatile boolean owned by commonMain,
     `writerDebugEnabled`. Off by default.
  2. InteropClient.main flips it to true if QUIC_INTEROP_DEBUG=1 is set
     in the env.
  3. Dockerfile + Makefile accept --build-arg DEBUG=1 (or `make build
     DEBUG=1`) to bake the env var into the image.

Usage:
  cd quic/interop
  make build DEBUG=1
  cd ../..
  ./quic/interop/run-matrix.sh -s aioquic -t multiplexing
  cat ../quic-interop-runner/logs/run-*/aioquic_amethyst/multiplexing/output.txt | grep '^\[writer'

When off, cost is one volatile read in the writer hot path — negligible.

https://claude.ai/code/session_01HcvfQq1ttPV9PkRoJb4nyT

quic/interop/Dockerfile

@@ -14,3 +14,10 @@ RUN apt-get update \
 COPY quic/interop/build/install/quic-interop /opt/quic-interop
 COPY quic/interop/run_endpoint.sh /run_endpoint.sh
 RUN chmod +x /run_endpoint.sh /opt/quic-interop/bin/quic-interop
+
+# Build-time toggle for verbose tracing. Pass --build-arg DEBUG=1 (or
+# `make build DEBUG=1` via the Makefile) to bake QUIC_INTEROP_DEBUG into
+# the image so the InteropClient + writer emit per-drain stats to stderr.
+# Off by default — production matrix runs stay quiet.
+ARG DEBUG=0
+ENV QUIC_INTEROP_DEBUG=${DEBUG}

quic/interop/Makefile

@@ -10,6 +10,11 @@ IMAGE     ?= amethyst-quic-interop:latest
 REPO_ROOT := $(shell git rev-parse --show-toplevel)
 DIST_DIR  := build/install/quic-interop
 
+# Build-time toggle: `make build DEBUG=1` bakes QUIC_INTEROP_DEBUG=1 into
+# the image so the InteropClient + writer emit per-drain diagnostics to
+# stderr. Off by default — production matrix runs stay silent.
+DEBUG     ?= 0
+
 .PHONY: build dist docker image-name clean
 
 build: docker
@@ -18,7 +23,7 @@ dist:
 	cd $(REPO_ROOT) && ./gradlew :quic-interop:installDist
 
 docker: dist
-	cd $(REPO_ROOT) && docker build -t $(IMAGE) -f quic/interop/Dockerfile .
+	cd $(REPO_ROOT) && docker build -t $(IMAGE) --build-arg DEBUG=$(DEBUG) -f quic/interop/Dockerfile .
 
 image-name:
 	@echo $(IMAGE)

quic/interop/src/main/kotlin/com/vitorpamplona/quic/interop/runner/InteropClient.kt

@@ -83,6 +83,12 @@ private const val PER_STREAM_TIMEOUT_SEC = 20L
 private const val MULTIPLEX_PARALLELISM = 64
 
 fun main() {
+    // Single env-var check, propagated to library code that opts into
+    // verbose tracing only when this is set.
+    if (System.getenv("QUIC_INTEROP_DEBUG") == "1") {
+        com.vitorpamplona.quic.connection.writerDebugEnabled = true
+    }
+
     val role = System.getenv("ROLE") ?: "client"
     if (role != "client") {
         System.err.println("server role not implemented")