Featherframe Cloud: a picture already drawn is shown without composing it again (W-1012)

[wr]

Most Cloud wakes switch the frames to a picture already in the drawn store: 14 of 18 on 7 Oct 2026 (W-1008). Each still composed the sheet to learn its ETag, which meant fetching and decoding the library crop and setting the type. That's about 0.3 CPU-s a wake on Cloud. Now each kept single sheet is found by what it was drawn from.

Stacked on #361. GitHub retargets this to main when that merges.

What changed

• Art names itself. ArtProvider.ref(common, scientific) returns the ref of the art artwork() would give, without loading or buying it: "" for none, None when it can't say (that composes as before). The ref covers:

  • a library plate: its crop key and everything its caption prints
  • a scan: its crop
  • a kept illustration: its sidecar, which every new drawing rewrites
  • no art at all (the chain's end): fallback

  Artwork.ref carries the same string.

• The drawn store remembers sheets. It keeps sheets: {key: {etag, art}} in its kv row, keyed by drawn.sheet_key: _drawn_from(spec), the art's ref, compose.SHEET_VERSION and the libraries. The pruner forgets a key once its ETag goes.

• _render_single uses it. A kept, whole sheet is committed by ETag with no pixels, and then finds its outputs, twin and views as before. Otherwise the sheet is composed, and kept under its key only if the art drawn has the ref the key named. The owner's Refresh always composes.

• _commit takes a kept sheet. It accepts etag plus the art's signature in place of sheet. History draws a missing thumbnail from the kept sheet.

• SHEET_VERSION is held by test_drawn_versions.py like COLOR_VERSION and FINISH_VERSION. AGENTS.md is updated.

Verified

• Full pytest passes. New tests:
  • a sheet drawn before is shown with no compose, no art loaded, nothing finished and nothing written, and every frame is served the bytes it had
  • other art, a new SHEET_VERSION, a ref the art doesn't match, a provider that can't say, Refresh, and a missing sheet file all compose again
  • a missing twin and history come back
  • the pruner forgets let-go keys
  • library, scan, chain and illustration refs
• Gray sheet hashes recorded in tests/fixtures/drawn-versions.json. Existing hashes are unchanged.
• A local cold wake against a fake front door: the picture switch goes from 0.123 to 0.037 CPU-s. On Cloud's slower vCPU that's ≈0.3 CPU-s less per such wake.

Left

• Import numpy, Pillow and the render modules only when drawing. That's ≈0.3 CPU-s more per wake, as a second PR.
• After deploy, measure with the hosted: stop lines (W-1008).

Refs W-1012

[linear-code]

W-1012