Gitea #51 ROOT CAUSE: LoopAtWill was mapped to "loop forever", arming 224 of 603 samples as endless OpenAL sources

SAURON's "coolant flush sound glitched and perma" is one instance of a systemic
defect.  SetupPatch (L4AUDLVL.cpp) decided looping from the SAMPLE flag alone:

    AL_LOOPING = (info.loop != ForceStatic)

That armed every non-ForceStatic sample -- 224 of the 603 authored zones,
including unmistakable one-shots -- as an OpenAL source that never ends on its
own.  Any such sound whose note-off never arrives plays forever.  Measured 1946
LoopAtWill x Transient arming events in one short session.

The sample flag expresses PERMISSION; the SOURCE decides.  Three facts [T1]:

  * the enum's own comments (L4AUDLVL.h:14-19) -- LoopAtWill = "will play once
    OR LOOP AS DESIRED", ForceStatic = "plays only once EVEN IF LOOPED" (a
    veto), LoopAlways = "ramp up and then down";
  * LoopAtWill is enum value 0, i.e. the DEFAULT an unauthored sample receives
    (WTPresets.cpp:37) -- it cannot mean "loop forever";
  * LoopAlways, the real always-loop, is used by ZERO shipped samples.

"As desired" is the source's authored AudioRenderType (Transient=one-shot vs
Sustained=held), streamed from AUDIO*.RES (AUDLVL.cpp:28) and already consulted
by the renderer (L4AUDRND.cpp:567, AUDREND.cpp:184).  SetupPatch now takes it,
threaded from all three L4AudioSource call sites (Direct/Dynamic3D/Static3D).
New rule: LoopAlways->1, ForceStatic->0, LoopAtWill->the source's render type.

MEASURED before changing behaviour (BT_LOOP_AUDIT=1, scratchpad/loopaudit.py):

    LoopAtWill  x Transient -> loop=0  (was 1)   1946 events
    LoopAtWill  x Sustained -> loop=1  unchanged    65 events
    ForceStatic x Transient -> loop=0  unchanged   292 events

The engine loops (EngineAccel07_z0..z2, EngineMotor01, EnginePower01) are all
LoopAtWill/Sustained and PRESERVED -- no regression there.  All 24 reclassified
samples are genuine one-shots: laser charge/fire/explosion/loaded, missile
loading, engine shift, coolant pressure inc/dec.

A/B PROOF (scratchpad/loopab.py, same session both arms, only BT_LOOP_LEGACY
differs), asking the engine's own BT_AUDIO_DUMP what is still playing with
loop=1 long after every release:

    [legacy] EnginePower01, CoolantPresInc03_z2, CoolantPresDcr03_z2
    [fixed]  EnginePower01

The two stuck coolant sources are the reported symptom.  They were eventually
reclaimed when a later trigger reused the source, which is why the bug was
intermittent -- the "perma" case is when nothing else retriggers it.  The fix
removes the mechanism.

BT_LOOP_LEGACY=1 restores the old rule for a field A/B without a rebuild.  The
layers to listen to are the beam sustains: LaserA/CSustain* are authored
LoopAtWill on a TRANSIENT source, so they now end with the sample instead of
looping until note-off.  The render type is T1 authored data; the interpretation
that LoopAtWill defers to it is a strong reading of the enum + defaults rather
than a disassembled statement, and is flagged as such in the KB.

Plausibly bears on #32 (audio cutting in/out late in a match): a stuck looping
source holds its pool slot for the rest of the round.

Rigs: scratchpad/flushsnd.py (flush start/stop pairing), flushsnd2.py (stuck-
source hunt), loopaudit.py (the classification matrix), loopab.py (the A/B).
KB: context/wintesla-port.md audio section, context/decomp-reference.md env
table (BT_LOOP_AUDIT / BT_LOOP_LEGACY / BT_AUDIO_DUMP / BT_AUD_TAIL),
docs/AUDIO_FIDELITY.md F38.  checkctx.py CLEAN.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

context/decomp-reference.md

@@ -368,6 +368,10 @@ default-ON (`'0'` disables).
 | `BT_GAUGE_ATTR_LOG` | `[attr] <binding> OK/NULL` per config binding |
 | `BT_GAUGE_SKIP_LOG` | `[gskip] <primitive>` per unregistered gauge widget the parse skips |
 | `BT_VALVE_LOG` | condenser valve flow distribution |
+| `BT_LOOP_AUDIT` | `[loop-audit]` per-sound `sample-flag × source-render-type -> AL_LOOPING` (Gitea #51; rig `scratchpad/loopaudit.py`) |
+| `BT_LOOP_LEGACY=1` | restore the OLD always-loop rule (`AL_LOOPING = sample != ForceStatic`) for a field A/B — see the loop-flag note in [[wintesla-port]] |
+| `BT_AUDIO_DUMP` | once-a-second `[playing]` dump of every playing AL source + gain/pitch/**loop** — catches a stuck looping source red-handed |
+| `BT_AUD_TAIL` | `[aud-tail]` timestamped PLAY/STOP/fade tracing per source |
 | `BT_SECTOR_LOG` | SectorDisplay Make/Execute |
 | `BT_NET_TRACE` | `[net-tx]/[net-rx]/[net-upd]` MP tracing |
 | `BT_DEV_GAUGES` | render the 6 pod MFD surfaces in a separate dev window |

context/wintesla-port.md

@@ -81,6 +81,29 @@ on top of it. Full detail: `docs/PROGRESS_LOG.md §5b, §8`.
     `MAX_PRESET_SAMPLES=25` (AllExplosion). Authored loop REGIONS apply via `AL_SOFT_loop_points`;
     authored `releaseVolEnv` (1.1–3.9 s on ~20 looping presets) fades on Stop
     (`PRESET_serviceReleaseFades`, serviced from `AudioHead::Execute`).
+  - **⚠ THE LOOP FLAG IS NOT THE LOOP DECISION (Gitea #51, 2026-07-25).** `SetupPatch`
+    (`L4AUDLVL.cpp`) used to map `AL_LOOPING = (sample != ForceStatic)`, which armed **224 of the
+    603 authored samples** as OpenAL sources that never end — any whose note-off never arrives plays
+    **forever** (SAURON: "coolant flush sound glitched and perma"). Three facts say the sample flag
+    only expresses PERMISSION, and the SOURCE decides [T1]:
+    (1) the enum's own comments (`L4AUDLVL.h:14-19`) — `LoopAtWill` = "will play once **or loop as
+    desired**", `ForceStatic` = "plays only once **even if looped**" (a veto), `LoopAlways` =
+    always; (2) `LoopAtWill` is enum value **0**, i.e. the DEFAULT an unauthored sample receives
+    (`WTPresets.cpp:37`) — it cannot mean "loop forever"; (3) `LoopAlways`, the real always-loop, is
+    used by **zero** shipped samples. "As desired" is the source's authored **`AudioRenderType`**
+    (`Transient`=one-shot vs `Sustained`=held), streamed from `AUDIO*.RES` (`AUDLVL.cpp:28`) and
+    already consulted by the renderer (`L4AUDRND.cpp:567`). New rule: `LoopAlways`→1,
+    `ForceStatic`→0, `LoopAtWill`→ the source's render type. **Measured** (`BT_LOOP_AUDIT=1`,
+    `scratchpad/loopaudit.py`): `LoopAtWill×Transient` 1946 events flip 1→0, `LoopAtWill×Sustained`
+    65 events stay 1, `ForceStatic×Transient` 292 unchanged — the engine loops
+    (EngineAccel07_z0-z2/EngineMotor01/EnginePower01) are all Sustained and **preserved**; all 24
+    reclassified samples are genuine one-shots (laser charge/fire/explosion, missile loading,
+    coolant pressure inc/dec). **A/B proof** (`scratchpad/loopab.py`): under the old rule
+    `CoolantPresInc03_z2` + `CoolantPresDcr03_z2` are still playing with `loop=1` after every
+    release; under the new rule zero coolant sources survive, engine loop intact. `BT_LOOP_LEGACY=1`
+    restores the old rule for a field A/B — listen to the beam-sustain layers (`LaserA/CSustain*` are
+    `LoopAtWill` on a Transient source, so they now end with the sample). A stuck looping source also
+    holds a pool slot for the rest of the match, so this plausibly contributed to **#32**'s dropouts.
   - **Distance/volume/doppler**: OpenAL distance model is `AL_NONE` — the AUTHORED
     `GetDistanceVolumeScale()` curve multiplies in `CalculateSourceVolumeScale` (Dynamic3D +
     Static3D); per-source `AL_GAIN = volume_scale²` (GM CC7 squared law); `alDopplerFactor(0)` —