# Adaptive command quality

The production profile leaves the Warcraft III command-capture cap at 40 FPS.
It does not reduce that cap. The actual frame rate follows the game and can be
lower on a loaded seat. The relay changes command precision and texture coding
when the measured path cannot carry the current demand.

## Profiles

The controller uses three tested profiles:

| Profile | Use | Texture policy |
|---|---|---|
| Q8 | Default | WebP quality 95, method 4 |
| Q6 | Shallow fallback and upgrade probe | WebP quality 80, method 4 |
| Q1 | Constrained-path fallback | WebP quality 40, method 4 |

Every profile preserves every source `Present`, draw, texture, state change,
and resource. Lower profiles use bounded screen-space geometry precision.
They do not remove game objects or draws. A quality change is committed at a
safe `Present` boundary and acknowledged back to the relay.

The relay measures frame demand, reliable-resource demand, delivered rate,
queue pressure, and blocked time. WebTransport also supplies an independent
BBR capacity estimate. DataChannel fallback uses sustained SCTP sender pressure
as its primary signal. Two browser-arrival deficits against the relay's actual
sent frame rate provide a secondary signal for unordered SCTP loss. After two
clean reports it probes upward in bounded Q1 to Q6 to Q8 steps because a
send-limited receive counter cannot reveal unused capacity. The controller can
move directly from Q8 to Q1 during heavy pressure. There is no fixed 15-second
ramp.

## Texture path

Supported immutable texture definitions use WebP method 4. Encoding and disk
loads run in a bounded background worker. A cache miss sends the exact raw
texture for the current session. A later use can use the cached WebP variant.
This rule keeps disk and encoder latency out of the capture path.

During the method-0 to method-4 migration, the relay checks the requested
method-4 key first and then the matching method-0 key. A method-4 miss queues
one background job. That job checks method 4 on disk, loads an existing method
0 entry when available, and encodes only method 4. Thus an old entry can serve
while method 4 warms, but the relay never creates a new method-0 entry. The
normal disk limit and eviction policy remove old entries over time.

The cache key includes the exact source pixels, texture layout, WebP policy,
alpha handling, and encoder version. Q8, Q6, and Q1 therefore have separate
safe variants. The relay hashes source pixels once and derives the three
quality keys, plus any temporary method-0 migration keys, from that digest.
A lower profile can temporarily use a cached higher-quality variant. A higher
profile never uses a lower-quality variant.

Game-generated geometry blobs use the lower 31 bits of the blob ID space.
Relay-generated WebP blobs use the high-bit namespace. The browser therefore
cannot confuse a texture image with current, retired, or future geometry.

All seats on one worker share the `webp-cache-v2` host-local cache. The v2
directory is separate from older relays that do not maintain its crash-safe
usage ledger. Normal writes update the ledger without scanning the directory.
A missing, dirty, or corrupt ledger causes one background repair scan. The
release defaults are:

- 24 GiB and 65,536 permanent entries on disk;
- 64 MiB memory front per relay;
- 32 MiB pending raw work per relay;
- two encoder slots across the host;
- 256 MiB and 8,192 entries for the exact texture mirror per relay;
- 192 MiB and 4,096 entries in browser IndexedDB.

WebP objects stay in the live stream and host cache. They do not enter R2,
the replay pack, or the generic raw-resource spool.

## Measured result

The isolated Worker 1 canary on 2026-08-24 passed:

- 12.9 MiB of raw texture payload became 2.1 MiB of WebP, an 83.6% reduction;
- Q8 changed to Q1 in 2.029 seconds under a deterministic 6 Mbps decision cap;
- Q1 returned to Q8 in 1.960 seconds after the cap was removed;
- source cadence stayed at 40 FPS and browser rendering stayed near 39 FPS;
- the original method-0 canary encoded 60 entries in 123.8 ms total;
- no stream errors, recovery storms, encode errors, corrupt cache entries, or
  texture ID collisions occurred.

Two locked 10-second windows preserved every `Present` and draw. Q1 reduced
post-zstd application bytes by 53.13% in the first window and 51.54% in the
later window. The zstd policy is frame level 6 and reliable level 3 for every
quality profile. On the locked texture corpus, method 4 reduced the Q80 WebP
payload by 20.1% relative to method 0. Because texture bytes are only part of
the stream, the extra complete-stream reduction was 0.6% to 1.3% across the
three profiles.

## Rollout

Roll out one worker at a time. Keep Q8 as the default. Monitor quality target
and effective state, frame and reliable Mbps, delivered rate, BBR capacity,
queue pressure, recovery count, WebP hits, disk loads, encodes, evictions,
method-0 fallbacks, raw fallbacks, directory repair scans, entry count, and
free disk. Expand to all seats only after the worker smoke test passes.