jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-quic-transport

Commentary: Could we also maybe add a pointer to the requirement that a DCID in an Initial must be eight bytes to Section 17.2 ? Because at the moment , it 's buried in Section 7.2 , where I did n't find it . 
 I 've taken this change manually , after reverting the change to the invariants doc . After looking at this more closely , the invariants doc does not include specifics of how to generate a Version Negotiation packet and this takes an awkward step in that direction . Rather than start to import the rules into invariants piecemeal like this , I think that it is cleaner to leave the rules for generating a Version Negotiation packet as version - specific , which is already clearly the case . 
  : I missed the bit about this being a blanket " version - specific rules for packets " . I 've changed this to " version - specific rules for connection IDs " , to reflect the context better . And to avoid tripping up on the packet size rules in version 1 . 
 Since future QUIC versions might have different CID length requirements for Initial packets ( or however that packet type will be called in that version ) , we already require servers to be able to send Version Negotiation packets with CIDs longer than 20 bytes ( which is the maximum length that v1 allows ) . We need to clarify that this also applies to the minimum CID length , which is 8 byte for the DCID in v1 . A future version of QUIC might relax this limit , so a server also needs to generate a VN packet if it receives a packet with an unknown version and a shorter  , otherwise it wo n't be possible to roll out such a QUIC version . This is coming out of a Slack discussion with and as well as recent tests on the interop runner . It turns out that 2 server implementations on the interop runner did n't get this right , and at least one server implementation that 's not on the interop runner , but is running QUIC in production . 
 I think the CID specific aspect is fine . It is unclear what other aspects that are specified by the protocol and are not invariant here .
Paragraph (version A):
Future versions of QUIC may have different requirements for the
lengths of connection IDs larger than version 1.  In particular,
connection IDs might not be required to have a minimum lengths, and
might be longer than 20 bytes.  A server therefore MUST respond with
a Version Negotiation packets for all lengths of connection IDs
allowed by the layout defined here.
Paragraph (version B):
Future versions of QUIC may have different requirements for the
lengths of connection IDs.  In particular, connection IDs might have
a smaller minimum length or a greater maximum length.  Version-
specific rules for QUIC packets therefore MUST NOT influence a server
decision about whether to send a Version Negotiation packet.
Draft: draft-ietf-quic-recovery

Commentary: So there are a couple of section references in the doc that points the wrong section in other documents . Section 6.2.1 : " A sender SHOULD restart its PTO timer every time an ack - eliciting packet is sent or acknowledged , when the handshake is confirmed ( Section 4.1.2 of [ QUIC - TLS ] ) , or when Initial or Handshake keys are discarded ( Section 9 of [ QUIC - TLS ] ) " , should that last ref be to section 4.9 in QUIC - TLS?"Section 6.4 : " see Section 4.8 of [ QUIC - TLS ] ) " This is now Section 4.9.Section B.2 : maxdatagramsize : The sender 's current maximum payload size . Does not include UDP or IP overhead . The  datagram size is used for congestion window computations . An endpoint sets the value of this variable based on its PMTU ( see Section 14.1 of [ QUIC - TRANSPORT ] ) , with a minimum value of 1200 bytes . " Should that Section 14.1 reference be to 14.2 . 
 Thank you for catching these ,
Paragraph (version A):
A sender SHOULD restart its PTO timer every time an ack-eliciting
packet is sent or acknowledged, when the handshake is confirmed
(Section 4.1.2 of QUIC-TLS), or when Initial or Handshake keys are
discarded (Section 9 of QUIC-TLS).  This ensures the PTO is always
set based on the latest estimate of the round-trip time and for the
correct packet across packet number spaces.
Paragraph (version B):
A sender SHOULD restart its PTO timer every time an ack-eliciting
packet is sent or acknowledged, when the handshake is confirmed
(Section 4.1.2 of QUIC-TLS), or when Initial or Handshake keys are
discarded (Section 4.9 of QUIC-TLS).  This ensures the PTO is always
set based on the latest estimate of the round-trip time and for the
correct packet across packet number spaces.
Paragraph (version A):
When packet protection keys are discarded (see Section 4.8 of QUIC-
TLS), all packets that were sent with those keys can no longer be
acknowledged because their acknowledgements cannot be processed
anymore.  The sender MUST discard all recovery state associated with
those packets and MUST remove them from the count of bytes in flight.
Paragraph (version B):
When packet protection keys are discarded (see Section 4.9 of QUIC-
TLS), all packets that were sent with those keys can no longer be
acknowledged because their acknowledgements cannot be processed
anymore.  The sender MUST discard all recovery state associated with
those packets and MUST remove them from the count of bytes in flight.
Draft: draft-ietf-quic-transport

Commentary: Section 13.4.2 : If all packets marked with non - zero ECN codepoints are subsequently lost , it can disable marking on the assumption that the marking causes in loss . s / in / the ?
Paragraph (version A):
If an endpoint has cause to expect that IP packets with an ECT
codepoint might be dropped by a faulty network element, the endpoint
could set an ECT codepoint for only the first ten outgoing packets on
a path, or for a period of three PTOs (see Section 6.2 of QUIC-
RECOVERY).  If all packets marked with non-zero ECN codepoints are
subsequently lost, it can disable marking on the assumption that the
marking causes in loss.
Paragraph (version B):
If an endpoint has cause to expect that IP packets with an ECT
codepoint might be dropped by a faulty network element, the endpoint
could set an ECT codepoint for only the first ten outgoing packets on
a path, or for a period of three PTOs (see Section 6.2 of QUIC-
RECOVERY).  If all packets marked with non-zero ECN codepoints are
subsequently lost, it can disable marking on the assumption that the
marking caused the loss.
Draft: draft-ietf-quic-transport

Commentary: The spec says : First of all , I have no idea what a " corruption of state " is supposed to be . More importantly , the second sentence seems to suggest that if an error only affects a single stream , it might not be required to send a connection - level error . I 'm thinking of a stream - level flow control violation . 
 The challenge here is that the transport does n't define how streams can be used by application layer protocols , but seems to want to strongly encourage how an application uses error codes . An example of " corruption of state " is something like a QPACK error that renders the HTTP/3 connection unusable because the QPACK state can not be assured . In contrast , an application might treat receiving a header with an uppercase field name as a stream error that otherwise would not affect the rest of the H3 connection . 
 Anything remain to be done here ? 
 It seems like is interpreting this sentence as only applying to application protocol errors . If that 's the intention , we should make that clear : 
 It 's not exclusive to the application . Another example of corrupt state at the transport layer is CRYPTOBUFFEREXCEEDED -- you had to drop some bytes , so now your TLS handshake state is corrupted . As to the second piece , I think you 're reading that backward . A stream error MAY always be promoted to a connection error if the implementation decides it 's severe enough ; it does n't say anything about deciding to downplay errors if they 're localized . If an error is defined to be a connection error , it 's a connection error . If it 's defined to be a stream error , however , you 're always allowed to decide it 's the last straw and walk away . 
 QUIC transport does not have stream - level errors , though applications can . As such , the last sentence references a circumstance that does not exist in the transport draft . So the best solution seems to be to remove the last sentence . 
 : to your two points : " corruption of state that affects an entire connection " is clear that if the connection state is affected then it should result in a connection error agree that the second sentence seems unnecessary entirely , since stream - level errors are always treated as connection errors within the transport .
Paragraph (version A):
Errors that result in the connection being unusable, such as an
obvious violation of protocol semantics or corruption of state that
affects an entire connection, MUST be signaled using a
CONNECTION_CLOSE frame (frame-connection-close).  An endpoint MAY
close the connection in this manner even if the error only affects a
single stream.
Paragraph (version B):
Errors that result in the connection being unusable, such as an
obvious violation of protocol semantics or corruption of state that
affects an entire connection, MUST be signaled using a
CONNECTION_CLOSE frame (frame-connection-close).
Draft: draft-ietf-quic-recovery

Commentary: N was introduced in to describe how a sender might pace at a rate that allows it to send a congestion window 's worth of data in a period that is shorter than an RTT . This PR clarifies text that goes into unnecessary detail , trying to describe assumptions ( the network is spreading the packets out , for example , resulting in an ack clock ) . 
 Can we make progress in this one ? 
 Yes , I 'm waiting for the design issues to get done before moving on the remaining editorial ones . 
 I think that has happened now :-) 
 Nudge
Paragraph (version A):
Using a value for "N" that is small, but at least 1 (for example,
under-utilization of the congestion window.  Values of 'N' larger
than 1 ultimately result in sending packets as acknowledgments are
received rather than when timers fire, provided the congestion window
is fully utilized and acknowledgments arrive at regular intervals.
Paragraph (version B):
Using a value for "N" that is small, but at least 1 (for example,
under-utilization of the congestion window.
Draft: draft-ietf-quic-qpack

Commentary: This saves bytes ( that 's the most important reason ) . This uses something positive rather than something negative to define the instruction . Yes , it means that there are two " Literal"s in the name of an instruction . But now it says what is inside rather than what is n't . 
 I ca n't solve all the problems :) I think that in HPACK " literal " was reserved for the value more than the name . Maybe this only highlights that ... 
 I understand . This commit at least solves some of them , thank you for the improvement ! 
  is in the eye of the beholder . What am I to do with all the " wonr " variable names ? 
 Without Name Reference might be better replaced as " With Literal Name " ( Damn my enter key ... ) 
 Also consider changing on line 1640 , but GitHub wo n't let me comment that far from a change . I think this is an improvement . It has always bothered me that " literal field line " is used in sitations when only part of the field line is literal , and this change does not address that . An alternative would be : insert with literal name = insert literal field line ( or literal entry ) literal field line with name reference = field line with name reference and literal value literal field line with literal name = literal field lineSeems like a sensible change .
Paragraph (version A):
The literal field line without name reference representation encodes
a field name and a field value as string literals.
Paragraph (version B):
The literal field line with literal name representation encodes a
field name and a field value as string literals.
Draft: draft-ietf-quic-invariants

Commentary: I ca n't stop re - reading this text . There is n't much of it , but that makes it easier to spot little annoyances like this .
Paragraph (version A):
It is possible that middleboxes could use traits of a specific
version of QUIC and assume that when other versions of QUIC exhibit
similar traits the same underlying semantic is being expressed.
There are potentially many such traits; see bad-assumptions.  Some
effort has been made to either eliminate or obscure some observable
traits in QUIC version 1, but many of these remain.  Other QUIC
versions might make different design decisions and so exhibit
different traits.
Paragraph (version B):
It is possible that middleboxes could observe traits of a specific
version of QUIC and assume that when other versions of QUIC exhibit
similar traits the same underlying semantic is being expressed.
There are potentially many such traits; see bad-assumptions.  Some
effort has been made to either eliminate or obscure some observable
traits in QUIC version 1, but many of these remain.  Other QUIC
versions might make different design decisions and so exhibit
different traits.
Draft: draft-ietf-quic-transport

Commentary: I tried to just make a note here saying " if you do n't send many packets , you wo n't send many packets " , but then decided that  is probably more sensible . As it is , 3 RTT is the value that the PTO is initialized to ( validation almost always happens on a new path ) . And the loss of a single packet just does n't cut it . Even 3 packets ( the first packet , plus two on PTO , assuming two are sent on PTO ) is not that strong , but at least it is n't insanely tight . 
 and describe ECN validation and they say : dropped by a faulty network element , an endpoint could set the ECT(0 ) codepoint for only the first ten outgoing packets on a path , or for a period of three RTTs , whichever occurs first . Initial PTO timeout is also 3RTT . If client does not get ACK for its first flight Initial , after 3RTT later , it resends Initial without ECT set because client is now in " UNKNOWN " state . If the first client Initial is really lost , ECN validation fails . It seems to me that it would be better to lengthen timeout or ensure enough packets are sent not limited by the timeout ? 
 It seems like this particular problem was introduced by reducing the initial RTT from 500ms to 333ms ( in ) . 
 We use 3*PTO everywhere else , so suggesting it here makes sense to me .
Paragraph (version A):
If an endpoint has cause to expect that IP packets with an ECT
codepoint might be dropped by a faulty network element, the endpoint
could set an ECT codepoint for only the first ten outgoing packets on
a path, or for a period of three RTTs.  If all packets marked with
non-zero ECN codepoints are subsequently lost, it can disable marking
on the assumption that the marking causes in loss.
Paragraph (version B):
If an endpoint has cause to expect that IP packets with an ECT
codepoint might be dropped by a faulty network element, the endpoint
could set an ECT codepoint for only the first ten outgoing packets on
a path, or for a period of three PTOs (see Section 6.2 of QUIC-
RECOVERY).  If all packets marked with non-zero ECN codepoints are
subsequently lost, it can disable marking on the assumption that the
marking causes in loss.
Draft: draft-ietf-quic-invariants

Commentary: Issue raised by via : OLD:/At the endpoint , the connection ID is used to identify which QUIC connection the packet is intended for./ NEW:/At the endpoint , the connection ID is used to identify the QUIC connection for which the packet is    good . I 'll do that too .
Paragraph (version A):
The primary function of a connection ID is to ensure that changes in
addressing at lower protocol layers (UDP, IP, and below) do not cause
packets for a QUIC connection to be delivered to the wrong QUIC
endpoint.  The connection ID is used by endpoints and the
intermediaries that support them to ensure that each QUIC packet can
be delivered to the correct instance of an endpoint.  At the
endpoint, the connection ID is used to identify which QUIC connection
the packet is intended for.
Paragraph (version B):
The primary function of a connection ID is to ensure that changes in
addressing at lower protocol layers (UDP, IP, and below) do not cause
packets for a QUIC connection to be delivered to the wrong QUIC
endpoint.  The connection ID is used by endpoints and the
intermediaries that support them to ensure that each QUIC packet can
be delivered to the correct instance of an endpoint.  At the
endpoint, the connection ID is used to identify the QUIC connection
for which the packet is intended.
Draft: draft-ietf-quic-qpack

Commentary: This was in text pulled from RFC 7541 , so it 's excusable .
Paragraph (version A):
This is possible even over the Transport Layer Security Protocol
(TLS, see RFC5246), because while TLS provides confidentiality
protection for content, it only provides a limited amount of
protection for the length of that content.
Paragraph (version B):
This is possible even over the Transport Layer Security Protocol
(TLS, see TLS), because while TLS provides confidentiality protection
for content, it only provides a limited amount of protection for the
length of that content.
Draft: draft-ietf-quic-tls

Commentary: Too fast ! Thanks . 
 This will require rewrapping , which I can do if you prefer .
Paragraph (version A):
QUIC packet and framing add at least 36 bytes of overhead to the
ClientHello message.  That overhead increases if the client chooses a
connection ID without zero length.  Overheads also do not include the
token or a connection ID longer than 8 bytes, both of which might be
required if a server sends a Retry packet.
Paragraph (version B):
QUIC packet and framing add at least 36 bytes of overhead to the
ClientHello message.  That overhead increases if the client chooses a
source connection ID longer than zero bytes.  Overheads also do not
include the token or a destination connection ID longer than 8 bytes,
both of which might be required if a server sends a Retry packet.
Paragraph (version A):
Session resumption allows servers to link activity on the original
connection with the resumed connection, which might be a privacy
issue for clients.  Clients can choose not to enable resumption to
avoid creating this correlation.  Client SHOULD NOT reuse tickets as
that allows entities other than the server to correlate connections;
see Section C.4 of TLS13.
Paragraph (version B):
Session resumption allows servers to link activity on the original
connection with the resumed connection, which might be a privacy
issue for clients.  Clients can choose not to enable resumption to
avoid creating this correlation.  Clients SHOULD NOT reuse tickets as
that allows entities other than the server to correlate connections;
see Section C.4 of TLS13.
Paragraph (version A):
Packets protected with Initial secrets (initial-secrets) are not
authenticated, meaning that an attacker could spoof packets with the
intent to disrupt a connection.  To limit these attacks, Initial
packet protection keys can be discarded more aggressively than other
keys.
Paragraph (version B):
Packets protected with Initial secrets (initial-secrets) are not
authenticated, meaning that an attacker could spoof packets with the
intent to disrupt a connection.  To limit these attacks, Initial
packet protection keys are discarded more aggressively than other
keys.
Draft: draft-ietf-quic-tls

Commentary: This check really is triggered by TLS providing new keys , not QUIC delivering data on a higher encryption level . Otherwise , in the case where no session ticket is sent , this condition would go undetected for unconsumed data at the Handshake encryption level .
Paragraph (version A):
If the packet is from a new encryption level, it is saved for
later processing by TLS.  Once TLS moves to receiving from this
encryption level, saved data can be provided to TLS.  When
providing data from any new encryption level to TLS, if there is
data from a previous encryption level that TLS has not consumed,
this MUST be treated as a connection error of type
PROTOCOL_VIOLATION.
Paragraph (version B):
If the packet is from a new encryption level, it is saved for
later processing by TLS.  Once TLS moves to receiving from this
encryption level, saved data can be provided to TLS.  When TLS
provides keys for a higher encryption level, if there is data from
a previous encryption level that TLS has not consumed, this MUST
be treated as a connection error of type PROTOCOL_VIOLATION.
Draft: draft-ietf-quic-transport

Commentary: Please review carefully , but I think we can replace these paragraphs with a reference . 
 Nice find , thanks !
Paragraph (version A):
A server acknowledges the use of a Retry packet for a connection
using the retry_source_connection_id transport parameter; see
transport-parameter-definitions.  If the server sends a Retry packet,
it also subsequently includes the value of the Source Connection ID
field from the Retry packet in its retry_source_connection_id
transport parameter.
Paragraph (version A):
If the client received and processed a Retry packet, it MUST validate
that the retry_source_connection_id transport parameter is present
and correct; otherwise, it MUST validate that the transport parameter
is absent.  A client MUST treat a failed validation as a connection
error of type PROTOCOL_VIOLATION.
Paragraph (version B):
The connection IDs used on Initial and Retry packets exchanged
between client and server are copied to the transport parameters and
validated as described in cid-auth.
Draft: draft-ietf-quic-invariants

Commentary:  thought that it might be worth saying what QUIC is first . I agree . Tiny tweaks to the intro to allow for the change . Including a new title . 
 Issue raised by via : 
 I like it . I 'll see what that looks like .
Paragraph (version A):
In addition to providing secure, multiplexed transport, QUIC QUIC-
TRANSPORT includes the ability to negotiate a version.  This allows
the protocol to change over time in response to new requirements.
Many characteristics of the protocol will change between versions.
Paragraph (version B):
In addition to providing secure, multiplexed transport, QUIC QUIC-
TRANSPORT allows for the option to negotiate a version.  This allows
the protocol to change over time in response to new requirements.
Many characteristics of the protocol could change between versions.
Draft: draft-ietf-quic-recovery

Commentary: verified . Consistency in terms helps . 
 mentions /verification/ of ECN but defines /validation/ of ECN . : In section 9.2 : the term /verify/ is used 3 times , but not explained : /verifies ECN capability/ and /verifies ECN support/ should these both be /validates ECN support/ ? … ALSO is there a difference between ECN support and ECN capability ? - I did n’t expect a subtle difference , can we use one set of words instead ? ( and sorry if I compounded any confusion in the terms ... )
Paragraph (version A):
If a path has been verified to support ECN (RFC3168, RFC8311), QUIC
treats a Congestion Experienced (CE) codepoint in the IP header as a
signal of congestion.  This document specifies an endpoint's response
when its peer receives packets with the ECN-CE codepoint.
Paragraph (version B):
If a path has been validated to support ECN (RFC3168, RFC8311), QUIC
treats a Congestion Experienced (CE) codepoint in the IP header as a
signal of congestion.  This document specifies an endpoint's response
when its peer receives packets with the ECN-CE codepoint.
Paragraph (version A):
An endpoint verifies support for Explicit Congestion Notification
(ECN) by observing whether the ACK frames acknowledging the first
packets it sends carry ECN counts, as described in ecn-validation.
Paragraph (version B):
An endpoint validates support for Explicit Congestion Notification
(ECN) by observing whether the ACK frames acknowledging the first
packets it sends carry ECN counts, as described in ecn-validation.
Paragraph (version A):
The new path might not have the same ECN capability.  Therefore, the
endpoint verifies ECN capability as described in ecn.
Paragraph (version B):
The new path might not have the same ECN capability.  Therefore, the
endpoint validates ECN capability as described in ecn.