re: the GPU trace is compiled out of the release build -- both my guesses wrong

Last iteration left two candidates for why trace_gpu_stream produced no
file: the CLI flag not reaching the cvar, or BeginTracing failing
silently. Neither. Following the code instead of guessing:

BeginTracing only sets trace_state_ = kStreaming ("Streaming starts on
the next primary buffer execute"). The file is opened later, in
ExecutePrimaryBuffer, inside

  #if XE_ENABLE_TRACE_WRITER_INSTRUMENTATION == 1

and trace_writer.h defines that as 0 under NDEBUG, 1 otherwise -- the
trace writer exists only in debug builds.

Confirmed against the binaries, with a control. The format string
"{:08X}_stream.xtr" lives only inside that guard:

  build/bin/Linux/Release/xenia_canary          0 occurrences
  build/bin/Linux/Debug/xenia_canary            1 occurrence
  /sylph-home/re/canary-build/.../Release/...   0   <- what run-canary uses

The debug binary is the control: it proves the test finds the string when
it is present, so the release zero means something.

So trace_gpu_stream is a no-op in this container's emulator -- the cvar
parses, BeginTracing runs, and nothing can open a file. The kill -9 was
not the cause either, though it would have destroyed a trace had one
existed.

The route exists but is not cheap: a debug build with the writer compiled
in sits at build/bin/Linux/Debug/xenia_canary, 253 MB against Release's
18 MB, so a much slower boot plus a trace of every GPU packet on a disk
at 95%. Recorded as available rather than attempted -- what it would
confirm, the DC_LUT write, is already a well-supported inference, and the
cost is out of proportion to the gain.

METHOD: a cvar existing does not mean the feature is compiled in; and
test a compile-time gate against the binary, with a control.

docs/re/METHOD.md

@@ -663,3 +663,15 @@ agent's loop prompt, i.e. nowhere durable. See [`README.md`](README.md) for the
   a 2 GiB cap, so the experiment was safe regardless of how coarsely I polled.
   The watchdog never fired, which is the point — it cost nothing and removed the
   need to gamble on timing.
+* **A cvar existing does not mean the feature is compiled in.** `trace_gpu_stream`
+  parses, is documented, sets state, and does nothing: the code that opens the
+  trace sits behind `#if XE_ENABLE_TRACE_WRITER_INSTRUMENTATION == 1`, which
+  `trace_writer.h` ties to `#ifdef NDEBUG` — off in release. Two runs and two
+  wrong hypotheses before reading the `#if`. When a switch produces no effect,
+  follow the code from the switch to the output and look for a compile-time gate
+  before theorising about runtime causes.
+* **Test a compile-time gate against the binary, with a control.** A string that
+  exists only inside the guarded block (`_stream.xtr`) settles it in one command:
+  0 occurrences in the release binary, **1** in the debug binary. The debug build
+  is the control that proves the test can find the string when it is there —
+  without it, "0 occurrences" is just as consistent with a bad grep.

docs/re/REFUTED.md

@@ -489,3 +489,10 @@ neighbourhood, not just the line.
   `DC_LUT` ramp in the swap path. No emulator-side gamma post-process exists to
   subtract. 🟡 Whether this game installs a ramp at all is still unestablished.
   [`ui-render-tone-curve.md`](structures/ui-render-tone-curve.md)
+* "the GPU trace produced nothing because either the CLI flag did not reach the
+  cvar or `BeginTracing()` failed silently" → **both wrong.** The trace writer is
+  **compiled out**: `trace_writer.h` gates it on `#ifdef NDEBUG`, so a release
+  build has no writer at all. Confirmed with a control — the format string
+  `_stream.xtr` appears **once** in the Debug binary and **zero** times in the
+  Release binary `run-canary` actually uses.
+  [`capture-harness-status.md`](capture-harness-status.md)

docs/re/capture-harness-status.md

@@ -303,13 +303,50 @@ What the attempt did establish:
   routinely — can never finalise a trace.** The second run was therefore stopped
   with `SIGTERM` and exited cleanly. Still no file, so that is not the whole
   story.
-* Two candidates remain and were **not** separated: the CLI flag not reaching the
-  cvar, or `BeginTracing()` failing silently.
+* ~~Two candidates remain and were **not** separated: the CLI flag not reaching
+  the cvar, or `BeginTracing()` failing silently.~~
 
-**The next step is one run and removes the ambiguity:** set
-`trace_gpu_stream = true` in `xenia-canary.config.toml` itself rather than on the
-command line, and stop with `SIGTERM`. If a trace appears, the CLI path was the
-problem; if not, `BeginTracing` is.
+### ✅ Explained — and it was neither candidate
+
+**The trace writer is compiled out of the build in use.** Following the code:
+`BeginTracing()` only sets `trace_state_ = kStreaming` — *"Streaming starts on
+the next primary buffer execute"* — and the file is opened later, in
+`ExecutePrimaryBuffer`, inside
+
+```cpp
+#if XE_ENABLE_TRACE_WRITER_INSTRUMENTATION == 1
+```
+
+which `trace_writer.h` defines as:
+
+```cpp
+#ifdef NDEBUG
+#define XE_ENABLE_TRACE_WRITER_INSTRUMENTATION 0   // release
+#else
+#define XE_ENABLE_TRACE_WRITER_INSTRUMENTATION 1   // debug
+#endif
+```
+
+Confirmed in the binaries themselves, with a control. The format string
+`"{:08X}_stream.xtr"` exists only inside that guard:
+
+| binary | `_stream.xtr` occurrences |
+|---|---|
+| `build/bin/Linux/Release/xenia_canary` | **0** |
+| `build/bin/Linux/Debug/xenia_canary` | **1** |
+| `/sylph-home/re/canary-build/.../Release/xenia_canary` — **the one `run-canary` uses** | **0** |
+
+So `trace_gpu_stream` is a **no-op in this container's emulator**: the cvar
+parses, `BeginTracing` runs, and nothing can ever open a file. Neither the CLI
+flag nor `BeginTracing` was at fault, and neither was the `kill -9` — though that
+would have destroyed the trace too, had one existed.
+
+🟡 **The route exists but is not cheap.** A Debug build with the writer compiled
+in is present at `build/bin/Linux/Debug/xenia_canary` (253 MB against Release's
+18 MB). Running it means a much slower boot and a trace of every GPU packet on a
+disk at 95 %. Recorded as available rather than attempted — the thing it would
+confirm (the `DC_LUT` write) is already a well-supported inference, so the cost
+is out of proportion to the gain.
 
 ## ⚠️ The config dump in a log is the FILE, not the effective command line