settle verb: block until the client has finished drawing what a command just placed

[Flatts3000]

The proposal below is known to be wrong, and the comments say why. "Wait for the chunk
build queue to be empty" cannot work: getCompileQueueSize() measures backlog waiting for a
worker, not compiles in flight, so it reads near-zero throughout the work it is supposed to
detect. Measured on two clients, one with Sodium and one without. The goal in the first section
still stands; the mechanism does not.

The problem

shoot_scenes.py in the Recompile repo does this:

time.sleep(2.0)   # let the chunk meshes rebuild before grabbing the frame

That sleep is a guess. Too short and the screenshot catches a half-built world; too long and every
shoot pays for it. There is currently no way to ask the client whether it has finished drawing what
a command just placed.

The proposal

A verb that blocks until the client is visually settled, then replies. Roughly: the chunk build
queue is empty and at least one full frame has been rendered since it emptied.

{"verb": "settle"}
{"ok": true, "waitedMs": 840, "frames": 3}

Reporting how long it waited matters: a caller that sees 4000ms learns something a sleep(2) would
have hidden either way.

Why the mod and not a command

The chunk build queue is client render state. No command can see it, and no server-side signal
corresponds to it: the server considers a setblock done the instant it happens, which is exactly
the moment the mesh has not been rebuilt.

Notes

• Needs a timeout and a clear failure, in the style of the existing 30s command timeout.
• Worth reporting whether it gave up rather than settling, so a flaky shot is attributable.
• Probably the highest-value item available: it converts a known source of silent wrong output into
  a deterministic wait.

[Flatts3000]

Built it, and the premise does not hold. Halting rather than shipping it.

Branch: feat/settle-verb (not a PR, deliberately). It compiles, it is wired end to end, and it is
wrong in a way that would be worse than the sleep(2) it replaces.

What was built

settle waits for the chunk compile queue to be empty across N consecutive frames, sampling
LevelRenderer.getSectionRenderDispatcher().getCompileQueueSize() from a RenderFrameEvent.Post
listener, and reports waitedMs so a caller learns what the sleep was hiding.

What the measurement says

Against the Trashlands pack (Sodium 0.9.2 loaded):

Action	waitedMs	maxQueue
idle	45	0
after fill of ~30,000 blocks	75	0
25 consecutive single-frame samples during that fill	-	0 every time

The queue is never non-empty, even while tens of thousands of blocks are being remeshed. Sodium
keeps vanilla's dispatcher object and does not use its compile queue, so "queue empty" there means
"nobody is using this counter", not "the work is done".

So the verb returns in 70ms having proved nothing, and it looks authoritative while doing it. A
sleep(2) is at least honestly a guess.

Why this is a halt and not a fix

Three ways forward, and they are different products:

1. Frames only, honest about it. Drop the queue signal, wait N frames, and keep maxQueue in the
   reply so a caller can see the queue told us nothing. Cheap, ships today, strictly better than a
   sleep because it is adaptive and it reports - but it is not "wait until the work is done".
2. Integrate with Sodium. Ask its renderer instead when present. Real signal, at the cost of a
   compat dependency on a specific mod's internals, in a repo that currently depends on nothing.
3. Find a renderer-agnostic signal. Frame-time stability, or comparing successive frames.
   Heuristic, and heuristics are what this verb exists to replace.

That is a product decision about scope and dependencies, not something to guess at mid-loop.

One thing the exercise did prove

maxQueue is worth keeping whichever way this goes. A zero there is exactly what exposed the
problem, and it would expose the same problem for anyone whose client replaces the renderer.

Labelled question, matching #13 and #17, so an autonomous pass skips it until the call is made.

[Flatts3000]

Correction: the comment above is wrong. Sodium was a red herring.

I tested one client, saw a dead counter, and blamed the renderer replacement that happened to be
installed. Then I tested a client with no Sodium at all - Recompile's dev run, whose run/mods/
contains nothing but devbridge - and got the same result:

Client	after filling ~30,000 blocks
Trashlands (Sodium 0.9.2)	maxQueue: 0
Recompile dev run (no Sodium)	maxQueue: 0

So the Sodium hypothesis was unfalsifiable nonsense: I never ran the control.

What is actually wrong

The counter is alive. Teleporting into never-seen terrain and sampling 207 times over six seconds
caught it non-zero twice, peaking at 1.

That is the whole story. getCompileQueueSize() returns compileQueue.size(), the tasks waiting to
be handed to a worker. A background executor drains that queue as fast as it fills, so it reads
near-zero even while hundreds of sections are being meshed. It measures backlog, not work in
flight, and backlog is not what "has the client finished drawing" means.

An empty compile queue therefore means "nothing is waiting", which is true almost always, including
in the middle of the work we want to wait for. Two conditions built on that signal are two conditions
that are both trivially satisfied.

Where that leaves the design

SectionRenderDispatcher exposes only getCompileQueueSize() and getFreeBufferCount(). Neither
counts in-flight compiles, so there is no direct vanilla signal for "meshing is done".

Candidates, none yet tested:

• getFreeBufferCount() as a proxy. Buffers are checked out while a compile runs, so the free
  count should dip during work and recover after. Indirect, but it is a real observable.
• Plateau on countRenderedSections() or getSectionStatistics(). Wait for the rendered-section
  count to stop changing. Renderer-agnostic because it watches output rather than internals, but it
  is a heuristic, and heuristics are what this verb exists to replace.
• LevelRenderer.addRecentlyCompiledSection is called on completion. If NeoForge exposes a hook,
  counting completions and waiting for the rate to fall to zero would be the honest signal. Needs
  checking whether it is reachable without a mixin.

The question label stands, but for a better reason than the one I gave: not "Sodium blocks this"
but "vanilla exposes no direct signal, and the three candidates trade differently between accuracy
and coupling".

maxQueue still earns its place in the reply. It is what exposed both my wrong answer and the right
one.

[Flatts3000]

Parked. The goal still stands; the mechanism is falsified and choosing a replacement is not
urgent enough to hold up the rest of the queue.

State for whoever picks this up:

• Branch feat/settle-verb has the scaffolding, which is worth keeping: the per-frame listener, the
  client-only class wiring, the dispatch case, the CLI and Python surface, and maxQueue. Only one
  condition in it is dead - treating an empty compile queue as "work is done".
• That branch's commit message blames Sodium and is wrong. The comments above have the real
  cause. Do not take the commit message at face value.
• The useful artifact is the falsification test: teleport into never-seen terrain and sample
  continuously, requiring the counter to move. Filling 30,000 blocks barely registers; virgin chunk
  loading is what generates sustained work. Any candidate signal has to pass that before it is worth
  building on, or it is the same bug wearing a different counter.