nx_endgame.nx

nx_endgame.nx -- endgame last-piece racing for the fork-per-peer download model. module: nishi-core.torrent.endgame depends: nx_avail_map.nx (am_open/am_load + the locked-RMW flock idiom; transitively nx_pm_rarest, nx_pw_bitfield_has, nx_syscalls), nx_stream_picker.nx (nx_sp_in_endgame -- the canonical endgame-entry threshold; importing it un-orphans the streaming smart layer). capability: SWARM_INTELLIGENCE WHY: the dominant source of completion-time variance is the ONE slow peer holding the last piece. Our forked children normally AVOID duplicating work (they skip pieces already done via the donefile), which is correct for the bulk of a download. But in the TAIL -- when only a few obtainable pieces remain and they are all already in-flight on some (possibly slow) peer -- a child with nothing fresh should RACE one of those in-flight pieces from a second peer and let the faster connection win. This organ is that decision plus the shared IN-FLIGHT refcount map the children coordinate through. HONEST BOUNDARY: a piece that NO connected peer has (availability 0) can never be raced -- you cannot download data the swarm does not hold. eg_pick never returns such a piece; eg_obtainable_remaining excludes them. That is exactly the "stuck at 99.x%, no seeder has the last piece" reality -- the fix for THAT is webseed (BEP-19) / PEX (BEP-11), a later rung, not endgame. FILE FORMAT (download.inflight): npc bytes; byte p = saturating count (0..255) of children currently downloading piece p. Locked read-modify-write (same flock floor as the availability map).