perf: stop per-frame hardware endpoint re-enumeration by parking failed output sinks

[Yona-Appletree]

Plan: lp2025/2026-07-31-2224-hw-endpoint-status-cache
Path: ~/.photomancer/planning/lp2025/2026-07-31-2224-hw-endpoint-status-cache/plan.md

What this fixes

On projects/test/quad-strips the emulator profile attributed 45.8% of all
self cycles to HwRegistry::endpoint_status_for and 90.2% inclusive to
OutputProvider::open.

It turned out not to be a status-lookup problem at all. It was a failed-open
retry storm: ensure_channel_open re-attempted the open of any handle-less
sink every frame, forever, and each attempt enumerated the whole board — 256
endpoints, each with a formatted spec, a parse, a validate, and a live status
made of several registry lookups. fw-emu's board declared one WS281x channel
and no D9/D8/D7, so three of quad-strips' four sinks could never open and
paid that price sixty times a second.

So nothing is cached. A sink that opens successfully never asks again, so
there was no repeated query to memoize — and a cached Available on a claimed
pin would hand two owners the same hardware. Instead the registry gained the
invalidation primitive it lacked, and the flush seam stopped asking:

1. HwRegistry::generation() changes when a claim succeeds or a lease is
   released — the only two events that can turn a refusal into an acceptance.
   Failed claims deliberately do not bump.
2. OutputProvider::hardware_generation() forwards it (default 0 = static
   hardware).
3. EngineServices parks a failed sink on that value and skips it until the
   value changes. The generation is sampled before any open in the flush, so
   a claim made by this frame's own opens cannot park a sink against a number
   that already counts it.

Recovery is not slower for it: a released pin bumps the generation and the very
next flush picks the waiting sink up.

Measured

Frame-for-frame, 8 frames in both runs (events.jsonl B→E pairs):

	steady frame	total attributed	instructions
before	16.42M cycles	65,811,630	46,610,633
after	1.53M cycles	6,211,145	4,455,558

10.7× cheaper per steady frame. endpoint_status_for,
VirtualWs281xDriver::endpoints, endpoint_for_spec, validate_spec and the
core::fmt machinery are all absent from the top-20 self cycles. Per-frame
warn spam became 7 lines for the whole run.

What remains at the top is the sibling plan's target — memcpy, the allocator,
QueryKey::eq, SlotPath::parse: the dataflow resolver re-resolving from cold
each tick, owned by 2026-07-31-2225-persist-dataflow-resolution.

Also here

• One board survey per open, was three — the by-spec/by-address paths
  enumerated to pick an endpoint, again to find which driver owned the id, and
  the virtual driver again inside open to recover a GPIO the id already
  named. Error selection and driver ordering are unchanged, and a new test
  holds it to one pass.
• No per-frame OutputDef clones — refresh_output_sink_configs cloned
  every output's definition each tick to dodge a borrow, then almost always
  found nothing had changed. Now the tree and services are borrowed as the
  separate fields they are.
• fw-emu gets the S3's four WS281x channels — sequenced deliberately
  after the measurement, since making the endpoints exist first would have
  made the cost vanish without anything being fixed.

Honest scope note

On the desk S3 all four channels open on frame one, so silicon never paid this
in steady state and should be ~flat at its 20 fps. What silicon gains is that a
misconfigured output no longer costs a board enumeration and a serial log
line every frame it stays wrong.

The S3 fps was not re-measured: the board was not attached (the two ports
present were an esp32c6 and one that would not connect; identified via
espflash board-info, never auto-picked). That acceptance criterion is left
open rather than satisfied with a substitute board — see _DONE.md.

Phases

• P1 registry generation counter
• P2 OutputProvider::hardware_generation()
• P3 flush-seam retry policy + ADR
• P4 open path: one enumeration per attempt
• P5 refresh_output_sink_configs without per-frame clones
• P6 measure — emulator done; desk S3 blocked (device absent)
• P7 fw-emu board alignment, re-profile
• P8 docs, debt entry, cleanup

ADR: docs/adr/2026-07-31-output-sink-retry-policy.md
Debt: docs/debt/s3-frame-cost-scales-per-fixture.md — endpoint-status half
closed with numbers; resolver half explicitly still open, so the entry is not
marked resolved.

🤖 Generated with Claude Code