perf(hw): choose write_region's delta strategy by measured link cost

[kfox]

What

write_region decided how to split a changed region into writes by comparing byte counts: chunk when the dirty 256-byte slabs totalled under 60% of the region, otherwise push the whole region. Bytes are the wrong currency.

On socket DMA a write costs ~5.2 ms regardless of payload up to ~2.4 KB. Splitting a region into k pieces therefore multiplies its cost by k while the byte count obediently goes down — so the old rule was scored by a metric that could only ever say it was winning.

The choice is now a cost comparison against HardwareProfile.write_cost_s, max(floor, intercept + per_byte × B), measured per backend by a new diagnostic.

Why it belongs on the profile

The two links sit at opposite extremes and want opposite policies:

	fixed per write	marginal	knee	regime
Ultimate 64 (socket DMA)	5.22 ms	1.85 µs/B	~2.4 KB	write-count-bound
TeensyROM+ (USB serial)	0.29 ms	1.44 µs/B	~54 B	byte-bound

The marginal slopes agree within ~30% — both are the C64 bus at about a cycle a byte. What differs by 18× is the fixed per-write cost, which is the link protocol, and that single number inverts the right answer. The chunked branch still earns its place on the TeensyROM for the sparse-waveform case it was written for; it simply must not fire where the second write costs more than the bytes it saves.

Measurements

Offline, driving the real pipeline against real video (video_render_probe.py), the old rule was slower than not chunking on 19 of 19 firings across three display modes. One mhires clip lost 1083 ms over 400 frames, concentrated into 14 frames that each stalled ~77 ms — a visible hitch on scene cuts, which is exactly when a wide sparse dirty pattern occurs.

	before	after
mean frame	18.1 ms	13.3 ms
worst frame	104.4 ms	26.0 ms
mean bitmap push	4265 B	3280 B

On hardware, a minute of video per mode at unchanged write rate and frame rate: ~25% fewer bytes on the host-DMA bitmap path (220 → 166 KiB/s) and ~28% in the character modes (41 → 30 KiB/s).

The write rate deliberately does not move — the chunked branch fired on only ~3.5% of frames, so its cost lands in the worst frames rather than in an average. That is why the per-frame offline probe is the tool that can see it and a 10-second heartbeat average is not.

Also in here

• The separate full-push branch is gone. A span write is a subset of the same bytes and cost is monotonic in payload, so the span is never worse; "everything dirty" is just the case where the span is the whole region. This is the broader win on real content.
• full_threshold is removed from the write_region signature — no caller ever passed it, and it no longer names anything.
• New scripts/diags/link_cost_model.py, which is where the profile constants come from. It fits the two regimes separately: a single straight line through the flat part and the sloped part reports a healthy r² while understating both terms, and the floor is the term the decision turns on.
• video_render_probe.py now counts writes as well as bytes and prices frames with the profile's model, flagging any region split into more writes than pushing it whole would have cost.

Scope

With the REU enabled, [video].use_reu_staged = auto stages hires/mhires bitmaps through the REU bank-swap, which never reaches write_region — so on a default Ultimate the bitmap figures describe the host-DMA path, and what improves for those modes is screen and color RAM. Char modes are always on this path, as is everything on the TeensyROM+.

Verification

• make check green: ruff, mypy --strict, pyright, 3742 tests. make site-check green.
• New unit tests pin both regimes from one dirty pattern, and a randomised invariant test asserts the chosen strategy is never more expensive than one span write across four dirty densities on both profiles.
• On hardware: byte/write rates above, zero transport errors, and captured frames confirm mhires renders identically to the base — no corruption from the span-write offset, no new tearing.

[codecov]

Codecov Report

❌ Patch coverage is 93.75000% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 82.04%. Comparing base (53e8ce1) to head (4e9ee82).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
c64cast/hw/backend.py	93.75%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #275   +/-   ##
=======================================
  Coverage   82.03%   82.04%           
=======================================
  Files         142      142           
  Lines       24729    24731    +2     
  Branches     3628     3627    -1     
=======================================
+ Hits        20287    20291    +4     
+ Misses       3648     3647    -1     
+ Partials      794      793    -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.