jiebi/TextFlow huggingface dataset:
Original text:
See iana-error-codes for details of registering new error codes.  20.1. Application protocol error codes are 62-bit unsigned integers, but

Reviewer comments:
This just writes down what was proposed in .
Looks fine, but what about some guidance on stream vs connection errors? And also the principle of nearly always choosing a hard protocol violation error, or a more granular error with same effect?
Stream vs. connection is something that application protocols (like HTTP) need to worry about. The transport only concerns itself with connection errors. The idea that you pick the most helpful error is not something that we need to codify (in my view).
Isn't that worth mentioning? Or do we already have such text?
This is already discussed in Section 11, which makes me wonder if it would make more sense for text on this PR to be placed there too.
This I do not disagree with. I was merely suggesting that we explain why, as a general rule, a hard error is preferred as a design principle, not the nature of the error message which I do think should have a large degree of freedom.
Maybe there is a followup needed for the HTTP draft. If the principles are generally the same, we can copy the text and then add some more to cover the idea that we make most errors fatal to the connection rather than the stream.
I like Lucas suggestion of adding this text to the existing and already fairly complete text in section 11.
I moved the second paragraph up to the error handling section, but the text about how codes are selected really belongs with the codes themselves.
We don't really have any real principles that we agree on for deciding what error codes we are describing. Proposal: if the error carries distinct semantics (like stream rejection in HTTP), then it gets a new error code if the error is frequent or particularly significant, then it gets a new error code otherwise, target a more generic error code that identifies the broad area of the protocol finally, if there is no more specific applicable error code, use PROTOCOL_VIOLATION
is example of an issue discussed where it would have been useful to have principles.

Revised text:
See iana-error-codes for details of registering new error codes. <ins> In defining these error codes, several principles are applied.  Error conditions that might require specific action on the part of a recipient are given unique codes.  Errors that represent common conditions are given specific codes.  Absent either of these conditions, error codes are used to identify a general function of the stack, like flow control or transport parameter handling. Finally, generic errors are provided for conditions where implementations are unable or unwilling to use more specific codes. </ins> 20.1. Application protocol error codes are 62-bit unsigned integers, but
Original text:
process performed at the beginning of the connection SHOULD be applied for all paths used by the connection. <del> In case multiple connections share the same network path, as determined by having the same source and destination IP address and UDP ports, endpoints should try to co-ordinate across all connections to ensure a clear signal to any on-path measurement points. </del> When the spin bit is disabled, endpoints MAY set the spin bit to any value, and MUST ignore any incoming value.  It is RECOMMENDED that endpoints set the spin bit to a random value either chosen

Reviewer comments:
As discussed, this is a) hard to do in all cases, b) impossible to do in many, and c) not that useful.
good
When multiple connections share the same network path or multiple connection IDs are used for the same path, using the spin bit is complicated by the difficulty in correlating forward and reverse flows. There is currently text that uses RFC 6919 language in the draft recommending coordination of the spin to avoid this problem. However, as , this coordination seems difficult and therefore unlikely. It also creates a strong signal that indicates that all the connections on the path are terminated at the same endpoint on both ends. Maybe we don't want to be generating that signal. Also, because this coordination can't be guaranteed, the on-path observer is forced to build code for correlating/segregating measurements by connection ID in the case where there is no coordination. Maybe it's best just to remove this recommendation entirely.
+1 to removing the recommendation, or changing the statement to just a caution (e.g., if you are to coalesce connections that spin, then you'd better be aware of ...). FWIW I am not sure if I agree with this observation. IIUC, the connections sharing a 5-tuple will be terminated by the same endpoint on both ends; it is impossible for a middlebox to coalesce multiple QUIC connections. It is impossible because CIDs can change mid-connection, and a middlebox cannot determine to where the packets containing the new CID must be sent.
There definitely needs to be a degree of coordination between the middlebox and the endpoints, but that doesn't mean that you can't use something like the quic-lb stuff on either end (or both ends).
Yes, I think it is better to remove that recommendation, but perhaps replace it with a note to observers.

Revised text:
process performed at the beginning of the connection SHOULD be applied for all paths used by the connection.  When the spin bit is disabled, endpoints MAY set the spin bit to any value, and MUST ignore any incoming value.  It is RECOMMENDED that endpoints set the spin bit to a random value either chosen
Original text:
Indicates that x is A bits long Indicates that x uses the prefixed integer encoding defined in <del> Section 5.1 of RFC7541, beginning with an A-bit prefix. </del>  Indicates that x is variable-length and extends to the end of the region.

Reviewer comments:
Use more uniform and more specific language in description of instructions, like "follows" instead of "includes" or implicit mention of a field. Add references to integer and string encodings where missing. Prefer internal references to external ones (also in Section 1.2). Explicitly allow a header block to not have any instructions after the mandatory prefix. Refer to Literal Header Field With Name Reference section in Literal Header Field Without Name Reference instead of verbatim repeating text on 'N' bit. Reshuffle sentences, insert references instead, remove sentences where references suffice.
Mostly good improvements; a few things to fix up further.

Revised text:
Indicates that x is A bits long Indicates that x uses the prefixed integer encoding defined in  <ins> prefixed-integers, beginning with an A-bit prefix. </ins> Indicates that x is variable-length and extends to the end of the region.
Original text:
An encoder informs the decoder of a change to the dynamic table capacity using an instruction which begins with the '001' three-bit <del> pattern.  The new dynamic table capacity is represented as an integer with a 5-bit prefix (see Section 5.1 of RFC7541). </del>  The new capacity MUST be lower than or equal to the limit described in maximum-dynamic-table-capacity.  In HTTP/3, this limit is the

Reviewer comments:
Use more uniform and more specific language in description of instructions, like "follows" instead of "includes" or implicit mention of a field. Add references to integer and string encodings where missing. Prefer internal references to external ones (also in Section 1.2). Explicitly allow a header block to not have any instructions after the mandatory prefix. Refer to Literal Header Field With Name Reference section in Literal Header Field Without Name Reference instead of verbatim repeating text on 'N' bit. Reshuffle sentences, insert references instead, remove sentences where references suffice.
Mostly good improvements; a few things to fix up further.

Revised text:
An encoder informs the decoder of a change to the dynamic table capacity using an instruction which begins with the '001' three-bit  <ins> pattern.  This is followed by the new dynamic table capacity represented as an integer with a 5-bit prefix (see prefixed- integers). </ins> The new capacity MUST be lower than or equal to the limit described in maximum-dynamic-table-capacity.  In HTTP/3, this limit is the
Original text:
After processing a header block whose declared Required Insert Count is not zero, the decoder emits a Header Acknowledgement instruction. <del> The instruction begins with the '1' one-bit pattern and includes the header block's associated stream ID, encoded as a 7-bit prefix integer.  It is used by the peer's encoder to know when it is safe to evict an entry (blocked-insertion), and possibly update the Known Received Count (known-received-count). </del>  If an encoder receives a Header Acknowledgement instruction referring to a stream on which every header block with a non-zero Required

Reviewer comments:
Use more uniform and more specific language in description of instructions, like "follows" instead of "includes" or implicit mention of a field. Add references to integer and string encodings where missing. Prefer internal references to external ones (also in Section 1.2). Explicitly allow a header block to not have any instructions after the mandatory prefix. Refer to Literal Header Field With Name Reference section in Literal Header Field Without Name Reference instead of verbatim repeating text on 'N' bit. Reshuffle sentences, insert references instead, remove sentences where references suffice.
Mostly good improvements; a few things to fix up further.

Revised text:
After processing a header block whose declared Required Insert Count is not zero, the decoder emits a Header Acknowledgement instruction.  <ins> The instruction begins with the '1' one-bit pattern which is followed by the header block's associated stream ID encoded as a 7-bit prefix integer (see prefixed-integers). This instruction is used as described in known-received-count and in state-synchronization. </ins> If an encoder receives a Header Acknowledgement instruction referring to a stream on which every header block with a non-zero Required
Original text:
When a stream is reset or reading is abandoned, the decoder emits a Stream Cancellation instruction.  The instruction begins with the <del> '01' two-bit pattern.  The instruction includes the stream ID of the affected stream encoded as a 6-bit prefix integer.  See state- synchronization. </del>  4.4.3. The Insert Count Increment instruction begins with the '00' two-bit <del> pattern.  The instruction specifies the total number of dynamic table inserts and duplications since the last Insert Count Increment or Header Acknowledgement that increased the Known Received Count for the dynamic table (see known-received-count).  The Increment field is encoded as a 6-bit prefix integer.  The encoder uses this value to determine which table entries might cause a stream to become blocked, as described in state-synchronization. </del>  An encoder that receives an Increment field equal to zero or one that increases the Known Received Count beyond what the encoder has sent

Reviewer comments:
Use more uniform and more specific language in description of instructions, like "follows" instead of "includes" or implicit mention of a field. Add references to integer and string encodings where missing. Prefer internal references to external ones (also in Section 1.2). Explicitly allow a header block to not have any instructions after the mandatory prefix. Refer to Literal Header Field With Name Reference section in Literal Header Field Without Name Reference instead of verbatim repeating text on 'N' bit. Reshuffle sentences, insert references instead, remove sentences where references suffice.
Mostly good improvements; a few things to fix up further.

Revised text:
When a stream is reset or reading is abandoned, the decoder emits a Stream Cancellation instruction.  The instruction begins with the  <ins> '01' two-bit pattern, which is followed by the stream ID of the affected stream encoded as a 6-bit prefix integer. This instruction is used as described in state-synchronization. </ins> 4.4.3. The Insert Count Increment instruction begins with the '00' two-bit  <ins> pattern, followed by the Increment encoded as a 6-bit prefix integer. The value of the Increment is the total number of dynamic table insertions and duplications processed by the decoder since the last time it sent a Header Acknowledgement instruction that increased the Known Received Count (see known-received-count) or an Insert Count Increment instruction.  The encoder uses this value to update the Known Received Count, as described in state-synchronization. </ins> An encoder that receives an Increment field equal to zero or one that increases the Known Received Count beyond what the encoder has sent
Original text:
4.5. <del> Header blocks contain compressed representations of header lists and are carried in frames on streams defined by the enclosing protocol. These representations reference the static table, or dynamic table in a particular state without modifying it. </del>  4.5.1.

Reviewer comments:
Use more uniform and more specific language in description of instructions, like "follows" instead of "includes" or implicit mention of a field. Add references to integer and string encodings where missing. Prefer internal references to external ones (also in Section 1.2). Explicitly allow a header block to not have any instructions after the mandatory prefix. Refer to Literal Header Field With Name Reference section in Literal Header Field Without Name Reference instead of verbatim repeating text on 'N' bit. Reshuffle sentences, insert references instead, remove sentences where references suffice.
Mostly good improvements; a few things to fix up further.

Revised text:
4.5.  <ins> A header block consists of a prefix and a possibly empty sequence of representations defined in this section.  Each representation corresponds to a single header field.  These representations reference the static table or the dynamic table in a particular state, but do not modify that state. Header blocks are carried in frames on streams defined by the enclosing protocol. </ins> 4.5.1.
Original text:
absolute index less than the Base, this representation starts with the '1' 1-bit pattern, followed by the "S" bit indicating whether the reference is into the static or dynamic table.  The 6-bit prefix <del> integer (see Section 5.1 of RFC7541) that follows is used to locate the table entry for the header name.  When S=1, the number represents </del>  the static table index; when S=0, the number is the relative index of the entry in the dynamic table.

Reviewer comments:
Use more uniform and more specific language in description of instructions, like "follows" instead of "includes" or implicit mention of a field. Add references to integer and string encodings where missing. Prefer internal references to external ones (also in Section 1.2). Explicitly allow a header block to not have any instructions after the mandatory prefix. Refer to Literal Header Field With Name Reference section in Literal Header Field Without Name Reference instead of verbatim repeating text on 'N' bit. Reshuffle sentences, insert references instead, remove sentences where references suffice.
Mostly good improvements; a few things to fix up further.

Revised text:
absolute index less than the Base, this representation starts with the '1' 1-bit pattern, followed by the "S" bit indicating whether the reference is into the static or dynamic table.  The 6-bit prefix  <ins> integer (see prefixed-integers) that follows is used to locate the table entry for the header field.  When S=1, the number represents </ins> the static table index; when S=0, the number is the relative index of the entry in the dynamic table.
Original text:
than or equal to the Base, the representation starts with the '0001' 4-bit pattern, followed by the post-base index (see post-base) of the matching header field, represented as an integer with a 4-bit prefix <del> (see Section 5.1 of RFC7541). </del>  4.5.4.

Reviewer comments:
Use more uniform and more specific language in description of instructions, like "follows" instead of "includes" or implicit mention of a field. Add references to integer and string encodings where missing. Prefer internal references to external ones (also in Section 1.2). Explicitly allow a header block to not have any instructions after the mandatory prefix. Refer to Literal Header Field With Name Reference section in Literal Header Field Without Name Reference instead of verbatim repeating text on 'N' bit. Reshuffle sentences, insert references instead, remove sentences where references suffice.
Mostly good improvements; a few things to fix up further.

Revised text:
than or equal to the Base, the representation starts with the '0001' 4-bit pattern, followed by the post-base index (see post-base) of the matching header field, represented as an integer with a 4-bit prefix  <ins> (see prefixed-integers). </ins> 4.5.4.
Original text:
absolute index less than the Base, this representation starts with the '01' two-bit pattern. <del> Only the header field name stored in the static or dynamic table is used.  Any header field value MUST be ignored. </del> The following bit, 'N', indicates whether an intermediary is permitted to add this header to the dynamic header table on subsequent hops.  When the 'N' bit is set, the encoded header MUST

Reviewer comments:
Use more uniform and more specific language in description of instructions, like "follows" instead of "includes" or implicit mention of a field. Add references to integer and string encodings where missing. Prefer internal references to external ones (also in Section 1.2). Explicitly allow a header block to not have any instructions after the mandatory prefix. Refer to Literal Header Field With Name Reference section in Literal Header Field Without Name Reference instead of verbatim repeating text on 'N' bit. Reshuffle sentences, insert references instead, remove sentences where references suffice.
Mostly good improvements; a few things to fix up further.

Revised text:
absolute index less than the Base, this representation starts with the '01' two-bit pattern.  The following bit, 'N', indicates whether an intermediary is permitted to add this header to the dynamic header table on subsequent hops.  When the 'N' bit is set, the encoded header MUST
Original text:
RETIRE_CONNECTION_ID frames and retransmitted if the packet containing them is lost.  PING and PADDING frames contain no information, so lost PING or PADDING frames do not require repair.

Reviewer comments:
Is that not implied by the text here?
Kind of, but this text talks about the sender's perspective. Furthermore, checking for duplicates is inherently racy if you're using tokens for new connections while the old connection is still alive.
You know, I think that I put some proposed fixes for this in c016639e39c with rather than this branch. Moved it over here. NAME you approved , so I hope that moving that commit over here works for you.
Sec 13.2 of QUIC Transport explains what to do for the loss of a packet for every stream type except NEW_TOKEN. IMO it's nice but not critical to repair this loss, but I care less about how we resolve it than that we write it up.
Somewhat related question: Does this section fit better in the recovery draft?
I don't think so. This talks about the repair semantics of these frames, not the process of detecting loss. Recovery doesn't care about the distinction between PING and STREAM when it comes to repair.
LGTM, but do we need some text saying that when receiving a NEW_TOKEN frame, you MUST make sure that it's not a duplicate? Otherwise, a client might just save the token twice, and effectively reuse the token.

Revised text:
RETIRE_CONNECTION_ID frames and retransmitted if the packet containing them is lost. <ins> NEW_TOKEN frames are retransmitted if the packet containing them is lost.  No special support is made for detecting reordered and duplicated NEW_TOKEN frames other than a direct comparison of the frame contents. </ins> PING and PADDING frames contain no information, so lost PING or PADDING frames do not require repair.
Original text:
An opaque blob that the client may use with a future Initial packet.  19.8. STREAM frames implicitly create a stream and carry stream data.  The

Reviewer comments:
Is that not implied by the text here?
Kind of, but this text talks about the sender's perspective. Furthermore, checking for duplicates is inherently racy if you're using tokens for new connections while the old connection is still alive.
You know, I think that I put some proposed fixes for this in c016639e39c with rather than this branch. Moved it over here. NAME you approved , so I hope that moving that commit over here works for you.
Sec 13.2 of QUIC Transport explains what to do for the loss of a packet for every stream type except NEW_TOKEN. IMO it's nice but not critical to repair this loss, but I care less about how we resolve it than that we write it up.
Somewhat related question: Does this section fit better in the recovery draft?
I don't think so. This talks about the repair semantics of these frames, not the process of detecting loss. Recovery doesn't care about the distinction between PING and STREAM when it comes to repair.
LGTM, but do we need some text saying that when receiving a NEW_TOKEN frame, you MUST make sure that it's not a duplicate? Otherwise, a client might just save the token twice, and effectively reuse the token.

Revised text:
An opaque blob that the client may use with a future Initial packet. <ins> An endpoint might receive multiple NEW_TOKEN frames that contain the same token value.  Endpoints are responsible for discarding duplicate values, which might be used to link connection attempts; see validate-future. </ins> 19.8. STREAM frames implicitly create a stream and carry stream data.  The