docs: align comments with the code they describe

- multi_coalesce/batch: the ordering contract now states what Flush
  actually guarantees -- per-flow DATA order -- and names the two
  shapes later data may legally overtake (pure ACKs by design, and
  unparseable in-flow shapes as an accepted tradeoff).
- validVnetHdr claimed DATA_VALID makes the stack skip L4 checksum
  verification; the tun write path ignores that bit entirely. What the
  header buys is the absence of NEEDS_CSUM.
- tun_darwin Write said "only valid for single threaded use"; it is
  concurrency-safe and concurrent callers exist.
- udp_coalesce eviction comment said "Seal it" but never sets sealed.
- recordCapability: note the gauges are process-global while the state
  is per-socket (last writer wins).
- drop a stale tunReadBufSize reference.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014ugV2edVqoz3tBvq9J6yWp

overlay/batch/batch.go

@@ -5,7 +5,12 @@ import "net/netip"
 type RxBatcher interface {
 	// Commit commits pkt to be flushed by the batch. The caller must keep pkt valid until the next Flush, and not re-use it.
 	Commit(pkt []byte) error
-	// Flush emits every queued packet in arrival order.
+	// Flush emits every queued packet. The guarantee is per-flow DATA order:
+	// a flow's payload-bearing packets are never reordered relative to each
+	// other. Cross-flow and cross-lane order is not preserved, and two shapes
+	// may legally be overtaken by later same-flow data: pure ACKs (by design,
+	// stale ACKs are ignored) and unparseable shapes such as fragments (an
+	// accepted tradeoff; see MultiCoalescer).
 	// Returns the first error observed; keeps draining so one bad packet doesn't hold up the rest.
 	// After Flush returns, committed payload slices may be recycled.
 	Flush() error

overlay/batch/multi_coalesce.go

@@ -13,10 +13,21 @@ import (
 //
 // Lanes are processed independently: the TCP coalescer only sees TCP, the
 // UDP coalescer only sees UDP, and the passthrough lane handles everything else.
-// Per-flow delivery order is preserved because a single 5-tuple only
-// ever lands in one lane and each lane preserves its own slot order.
-// Routing follows the flow, not the coalesceability: IPv4 fragments keep
-// their L4 proto visible and IPv6 extension chains are walked to the
+// The ordering contract is per-flow DATA order: a flow's payload-bearing
+// packets are never reordered relative to each other, because a single
+// 5-tuple only ever lands in one lane and each lane emits its slots in
+// creation order. Two shapes are deliberately allowed to be overtaken by
+// later same-flow data:
+//   - pure ACKs, which pass through without sealing the flow's open slot
+//     (a late ACK is just a stale ACK; see TCPCoalescer.commitParsed);
+//   - unparseable in-flow shapes (fragments, IP options), whose lane-level
+//     addPassthrough does not close the flow's open slot either. Closing it
+//     would need a full open-slot barrier (the flow key is unknown when the
+//     parse fails) — an accepted tradeoff: mid-flow fragments are rare and
+//     receivers reassemble regardless of arrival order.
+//
+// Routing still follows the flow, not the coalesceability: IPv4 fragments
+// keep their L4 proto visible and IPv6 extension chains are walked to the
 // terminal proto, so a flow's non-coalesceable shapes ride its lane as
 // in-lane passthroughs rather than falling to the later-flushed pt lane.
 //

overlay/batch/udp_coalesce.go

@@ -160,7 +160,8 @@ func (c *UDPCoalescer) commitParsed(pkt []byte, info parsedUDP) error {
 			}
 			return nil
 		}
-		// Can't extend. Seal it and fall through to seed a fresh slot.
+		// Can't extend: evict it from openSlots and fall through to seed a
+		// fresh slot. (Eviction only; sealed is never set here.)
 		delete(c.openSlots, info.fk)
 		if c.lastSlot == open {
 			c.lastSlot = nil