Rate control: rebuilt per-frame, wired in, and gated at zero drift

FINDINGS 26 stopped the session-5 rate controller before it shipped: it built a
lam-ladder of independent whole-sequence encodes and picked frames off it, so
SKIP blocks referenced reconstructions the decoder never saw -- 111 of 120
frames drifted. The fix is the structural one 26.1 said it had to be.

vq_hybrid is now frame-drivable -- frame_ctx / decide / paint -- and encode() is
a thin loop over it. Rate control drives the same three calls, bisects lam per
frame under the leaky bucket, and feeds back the frame it actually emitted. The
desync has no way to occur, and 09_ratectl_drift.py goes 111/120 -> 0/120. That
test is now part of check.sh, which is ~2 min rather than ~40 s.

Both overshoots on the worst sustained window are closed for under 1 dB, totals
including audio: sasi 137.4 -> 109.5 KB/s (-0.60 dB), scsi 381.6 -> 280.0 KB/s
(-0.91 dB). Zero frames hit the lam=800 cliff, so nothing was destroyed to get
there. Rate control also makes the display path cheaper -- scsi's median drops
53.6% -> 47.1% -- because raising lam moves blocks to SKIP and V1.

Two knobs measured rather than guessed. --rc-floor is worth 0.00 dB on that
window and defaults to the profile lam, so rate control cannot regress content
that already fits. --prefill defaults to 0 and is documented as a trap: it buys
a permission to overshoot of exactly bucket/nframes, and on a 14-frame clip it
disables the controller outright.

FINDINGS 26.5 was wrong in both halves and 27.6 records it. _paint was not the
bottleneck (14% of a frame, though vectorising it was still right at 17.1x) and
the ladder was never "minutes" -- those were k-means in build(). What makes
per-frame rate control affordable is that VQ.assign depends on neither lam nor
prev, so it is cached one frame deep: a 12-step search over 120 frames costs
0.31 s against 49.1 s.

Also caught: fixed-lam sasi was already 5% over target on 00020, the clip
everyone called easy. Nothing noticed because the profile table quotes PSNR and
not bitrate.

check.sh: ALL GREEN.

Claude-Session: https://claude.ai/code/session_01194oWYW8DQXK1SZ2DnChW6

README.md

@@ -6,8 +6,9 @@ This is fundamentally a **video codec problem**, not a game-logic problem: the
 game logic is a scene table with branching input windows; the difficulty is
 pushing ~22 minutes of Don Bluth animation through a 10MHz 68000.
 
-**Green-light check:** `./tools/bench/check.sh` (~40 s, needs the Blu-ray
-mounted) re-runs both display regression tests and prints `ALL GREEN`.
+**Green-light check:** `./tools/bench/check.sh` (~2 min, needs the Blu-ray
+mounted) re-runs both display regression tests plus the rate-control drift test
+and prints `ALL GREEN`.
 
 ## Read first
 - **`docs/FINDINGS.md`** — measured hardware facts, content statistics, codec
@@ -27,9 +28,10 @@ tools/analysis/  measurement scripts, numbered in the order they were written
                  (01/02 marked BROKEN deliberately, kept as regression refs).
                  Run from the repo root — they import from tools/encoder/.
                  07 finds the hottest sustained window in a stream; 08 renders
-                 source | decoded | block-mode map as .webm; 09 is a regression
-                 test for the rate-control desync (FINDINGS 26) and exits
-                 non-zero until it is fixed.
+                 source | decoded | block-mode map as .webm; 09 is the
+                 rate-control drift gate (FINDINGS 26/27) and is part of
+                 check.sh -- it exits non-zero if the encoder ever again
+                 reports a reconstruction no decoder would produce.
 tools/bench/     MAME Lua injection harness + 68000 benchmark sources.
                  `check.sh` re-runs both display regression tests (~40 s).
                  `blit.s`/`blit.lua` time the full-frame GVRAM blit on the
@@ -51,7 +53,9 @@ python3 tools/encoder/encode.py  /tmp/fr out.dlx --profile sasi --preview p.png
 ```
 
 Two quality profiles ship from one codec and one decoder — `sasi` (110 KB/s) and
-`scsi` (280 KB/s) are two points on the same rate-distortion curve. The codec is
+`scsi` (280 KB/s) are two points on the same rate-distortion curve. Both are
+**ceilings**: lam is bisected per frame under a leaky bucket, so the profile's
+`lam` is a quality floor rather than a setting (`--fixed-lam` opts out). The codec is
 a Cinepak-style hybrid: each 4x4 block is coded as SKIP, one 4x4 codeword, four
 2x2 codewords, or RAW literal pixels, chosen per block by rate-distortion.