docs(terminal): correct two delivery-accounting comments that misstate the mechanism

`parkedCharsByPty` was documented as cumulative. It is a live balance,
decremented as each chunk settles, and the write-off subtracts it from a
genuinely cumulative `receivedChars` — mixing the two up is how someone
re-derives the predicate wrongly.

The "pauses the shell" claim is only true for ASCII-dominant output. This
buffer caps at 512KB of UTF-8 bytes while main's window counts UTF-16 chars,
so multi-byte output evicts and settles before main's window ever fills.
This commit is contained in:
Merge Sim
2026-09-07 14:32:53 -07:00
parent 1f11949835
commit 901764b2f2
2 changed files with 8 additions and 3 deletions
@@ -6,7 +6,9 @@
* call a wedge, so it was blind by construction, and the producer was never paused — main
* kept flooding a pane nobody could see. Holding the credit turns parked bytes into real
* debt, which is what makes main's existing per-PTY window pause the shell, the watchdog
* see the pane, and the write-off lane able to forgive it.
* see the pane, and the write-off lane able to forgive it. The pause is not guaranteed: this
* buffer caps at 512KB of UTF-8 BYTES while main's window counts UTF-16 CHARS, so on
* multi-byte output eviction settles the credit before main's window ever fills.
*
* Unit is delivery-credit CHARS (`rawLength ?? data.length`), never the buffer's UTF-8 byte
+5 -2
View File
@@ -19,8 +19,11 @@ export type PtyRendererDeliveryStateReport = {
* ACK path and resync response carry; merging them here is a free extra
* repair lane for the lost-ACK variant. */
processedCharsByPty: Record<string, number>
/** Cumulative chars received for a PTY that has no registered data handler and
* are parked in the renderer's pre-handler buffer. Their ACK is withheld, so —
/** Chars CURRENTLY parked for a PTY with no registered data handler — a live balance,
* decremented as each chunk settles, not a cumulative total like the fields either side
* of it. `writeOffLostRendererDelivery` subtracts it from a cumulative `receivedChars`
* precisely because of that: what is still parked is what cannot repay itself. Their ACK
* is withheld, so —
* unlike received-but-unparsed bytes, which their own deferred ACK repays —
* this debt has no consumer to repay it and only a write-off or a bind clears
* it. Absent means "none parked", which is exactly how an older renderer read. */