jiebi/TextFlow huggingface dataset:
Original text:
ConnectionError<> occurs when a Connection transitions to Closed state due to an error in all other circumstances.  The interface provides the following guarantees about the ordering of operations:

Reviewer comments:
Would be nice if someone has time to do some ascii art :-)
Wouldn't that be fig. 4 in the architecture draft? Except that, looking at this now, I see inconsistencies! E.g., I don't see "RendezvousDone" in the figure. Also, instead of ConnectionReceived, it says "Connection Received" - rather, this should probably marked as an event by writing it as "ConnectionReceived<>". The figure is also missing InitiateWithSend() ... probably it would be good to make this figure both complete and consistent with section 13, "Connection State and Ordering of Operations and Events", of the API draft? I don't think very much is missing there.
I think it would be nice to have a real state diagram here, probably with states like "closed", "open" and "listen" and the events that create a transition between these state.
I'm not sure that Figure 4 in the Arch diagram serves the purpose that Mirja's trying to address with the state diagram in API. I also don't think we need FIgure 4 to align with the specific naming and CamelCasingConventions in API.
Thanks! I guess you could add a loop for sent<> and received<> in established state but maybe that also too much.Works for me

Revised text:
ConnectionError<> occurs when a Connection transitions to Closed state due to an error in all other circumstances. <ins> The following diagram shows the possible states of a Connection and the events that occur upon a transition from one state to another. </ins> The interface provides the following guarantees about the ordering of operations:
Original text:
Transport Properties MUST always be specified while security parameters are OPTIONAL. <del> Message Framers (see framing), if required, should be added to the </del>  Preconnection during pre-establishment. 5.1.

Reviewer comments:
In the API doc sec 5 says. "Message Framers (see Section 10), if required, should be added to the Preconnection during pre-establishment." Should this be SHOULD or even MUST? If SHOULD is correct I think we need to say slightly more about when it makes sense to add a framer later.
I think it should be "can be added..."; not normative, just descriptive of fact.
Can we start with the "If' perhaps... "If messages frames are to be used, they MUST be added to the Preconnection during pre-establishment."?

Revised text:
Transport Properties MUST always be specified while security parameters are OPTIONAL.  <ins> If Message Framers are used (see framing), they MUST be added to the </ins> Preconnection during pre-establishment. 5.1.
Original text:
4.2.1. <del> Immediate, or simultaneous, racing should be avoided by implementations.  This approach can consume network resources and establish state that will not be used. </del>  4.2.2.

Reviewer comments:
I actually really like: "Simultaneous" and "Staggered" as descriptive terms that avoid the question of "delaying".
Opening this to follow up on a comment by NAME on that is now closed. "Simultaneous" and "Staggered" would be better names than "Immediate" and "Delayed". Just from these terms, I would normally think that "Immediate" means to start racing right away, whereas "Delayed" means that nothing would happen for some time. So these two terms are slightly misleading in my opinion.)
I agree this would be an improvement.
In Section 4.2.1., I didn't really understand what "immediate" means from the text. I think it just needs one sentence.
lgtm (side note - nothing blocking, this is just an idea: to me, "Simultaneous" and "Staggered" would be better names than "Immediate" and "Delayed". Just from these terms, I would normally think that "Immediate" means to start racing right away, whereas "Delayed" means that nothing would happen for some time. So these two terms are slightly misleading in my opinion.)Looks good, thanks! I will close this and open a separate issue for the naming.

Revised text:
4.2.1.  <ins> Immediate racing is when multiple alternate branches are started without waiting for any one branch to make progress before starting the next alternative.  This means the attempts are effectively simultaneous.  Immediate racing should be avoided by implementations, since it consumes extra network resources and establishes state that might not be used. </ins> 4.2.2.
Original text:
to an inbound SYN with a SYN-ACK. Calling "Clone" on a TCP Connection creates a new Connection with <del> equivalent parameters.  The two Connections are otherwise independent. </del>  SEND.TCP.  TCP does not on its own preserve Message boundaries. Calling "Send" on a TCP connection lays out the bytes on the TCP

Reviewer comments:
This provides more detail on how to implement Clone with TCP, and clarifies that SCTP's "Initiate" should not yield a stream of an already existing SCTP Association in case "activeReadBeforeSend" is Preferred or Required.
Currently the "Clone" part of, e.g., TCP (section 10.1) only says: "Calling Clone on a TCP Connection creates a new Connection with equivalent parameters. The two Connections are otherwise independent." This text should reflect that equivalent behavior must be maintained upon later Connection configuration calls. And, there should be more text in general on cloning (see issue ).
This text must refer to a new "do I want a Connection that supports initiate followed by listen?" property. This property will be added to address - so I'll address this issue when the PR addressing has landed.
Added a question for NAME

Revised text:
to an inbound SYN with a SYN-ACK. Calling "Clone" on a TCP Connection creates a new Connection with  <ins> equivalent parameters.  These Connections, and Connections generated via later calls to "Clone" on one of them, form a Connection Group.  To realize "entanglement" for these Connections, with the exception of "Connection Priority", changing a Connection Property on one of them must affect the Connection Properties of the others too.  No guarantees of honoring the Connection Property "Connection Priority" are given, and thus it is safe for an implementation of a transport system to ignore this property.  When it is reasonable to assume that Connections traverse the same path (e.g., when they share the same encapsulation), support for it can also experimentally be implemented using a congestion control coupling mechanism (see for example TCP-COUPLING or RFC3124). </ins> SEND.TCP.  TCP does not on its own preserve Message boundaries. Calling "Send" on a TCP connection lays out the bytes on the TCP
Original text:
If this is the only Connection object that is assigned to the SCTP association or stream mapping has not been negotiated, <del> CONNECT.SCTP is called.  Else, a new stream is used: if there are enough streams available, "Initiate" is just a local operation that assigns a new stream number to the Connection object.  The number of streams is negotiated as a parameter of the prior CONNECT.SCTP call, and it represents a trade-off between local resource usage and the number of Connection objects that can be mapped without requiring a reconfiguration signal.  When running out of streams, ADD_STREAM.SCTP must be called. </del>  If this is the only Connection object that is assigned to the SCTP association or stream mapping has not been negotiated,

Reviewer comments:
This provides more detail on how to implement Clone with TCP, and clarifies that SCTP's "Initiate" should not yield a stream of an already existing SCTP Association in case "activeReadBeforeSend" is Preferred or Required.
Currently the "Clone" part of, e.g., TCP (section 10.1) only says: "Calling Clone on a TCP Connection creates a new Connection with equivalent parameters. The two Connections are otherwise independent." This text should reflect that equivalent behavior must be maintained upon later Connection configuration calls. And, there should be more text in general on cloning (see issue ).
This text must refer to a new "do I want a Connection that supports initiate followed by listen?" property. This property will be added to address - so I'll address this issue when the PR addressing has landed.
Added a question for NAME

Revised text:
If this is the only Connection object that is assigned to the SCTP association or stream mapping has not been negotiated,  <ins> CONNECT.SCTP is called.  Else, unless the Selection Property "activeReadBeforeSend" is Preferred or Required, a new stream is used: if there are enough streams available, "Initiate" is just a local operation that assigns a new stream number to the Connection object.  The number of streams is negotiated as a parameter of the prior CONNECT.SCTP call, and it represents a trade-off between local resource usage and the number of Connection objects that can be mapped without requiring a reconfiguration signal.  When running out of streams, ADD_STREAM.SCTP must be called. </ins> If this is the only Connection object that is assigned to the SCTP association or stream mapping has not been negotiated,
Original text:
be sent in multiple parts. Protocols that provide the framing (such as length-value protocols, <del> or protocols that use delimiters) provide data boundaries that may be longer than the typical datagram.  Each Message for framing protocols </del>  corresponds to a single frame, which may be sent either as a complete <del> Message, or in multiple parts. </del>  5.1.

Reviewer comments:
Now I feel like I'm shaving the yak. This is more than what we talked about in the interim, but it felt like the following sentence required additional clarity. Let me know if I misunderstood the intended meaning, in which case I will rephrase.

Revised text:
be sent in multiple parts. Protocols that provide the framing (such as length-value protocols,  <ins> or protocols that use delimiters) may support Message sizes that do not fit within a single datagram.  Each Message for framing protocols </ins> corresponds to a single frame, which may be sent either as a complete  <ins> Message in the underlying protocol, or in multiple parts. </ins> 5.1.
Original text:
during Connection establishment.  This Message can potentially be received multiple times (i.e., multiple copies of the message data may be passed to the Remote Endpoint).  See also msg- <del> safelyreplayable.  Note that disabling this property has no effect for protocols that are not connection-oriented and do not protect against duplicated messages, e.g., UDP. </del>  4.2.6.

Reviewer comments:
The text says What does disabling mean? Does this mean mean that it is valid to set this property to "Prohibit" but still set "safelyReplayable" to "Require" on the PreConnection. Should that not be an error? This is also related to . The use of safelyReplayable for both reliable and unreliable services makes the text a bit confusing. Would it not be sufficient to state that if you do not Require Reliable Data Transfer you have to be prepared to deal with duplication?
We should remove this sentence in 4.2.5:

Revised text:
during Connection establishment.  This Message can potentially be received multiple times (i.e., multiple copies of the message data may be passed to the Remote Endpoint).  See also msg-  <ins> safelyreplayable. </ins> 4.2.6.
Original text:
a Preconnection allows applications to override this for more detailed control. <del> Transport Properties MUST always be specified while security parameters are OPTIONAL. </del> If Message Framers are used (see framing), they MUST be added to the Preconnection during pre-establishment.

Reviewer comments:
For other parameters you have to pass in an empty object if you do not want to set anything but not for SecurityParameters. Unclear why the parameters are treated differently?
Make security parameters non-optional Remove "Transport Properties MUST always be specified while security parameters are OPTIONAL." Define that there is an implementation-specific security parameter to disable security
LGTM, thanks!

Revised text:
a Preconnection allows applications to override this for more detailed control.  If Message Framers are used (see framing), they MUST be added to the Preconnection during pre-establishment.
Original text:
Session cache management: Used to tune session cache capacity, lifetime, and other policies.  Representation of Security Parameters in implementations should parallel that chosen for Transport Property names as recommended in scope-of-interface-defn.

Reviewer comments:
For other parameters you have to pass in an empty object if you do not want to set anything but not for SecurityParameters. Unclear why the parameters are treated differently?
Make security parameters non-optional Remove "Transport Properties MUST always be specified while security parameters are OPTIONAL." Define that there is an implementation-specific security parameter to disable security
LGTM, thanks!

Revised text:
Session cache management: Used to tune session cache capacity, lifetime, and other policies. <ins> Connections that use Transport Services SHOULD use security in general.  However, for compatibility with endpoints that do not support transport security protocols (such as a TCP endpoint that does not support TLS), applications can initialize their security parameters to indicate that security can be disabled, or can be opportunistic.  If security is disabled, the Transport Services system will not attempt to add transport security automatically.  If security is opportunistic, it will allow Connections without transport security, but will still attempt to use security if available. </ins> Representation of Security Parameters in implementations should parallel that chosen for Transport Property names as recommended in scope-of-interface-defn.
Original text:
transport layer, in line with developments in modern platforms and programming languages; <del> Selection between alternate network paths that can be informed by additional information that is available about the networks over </del>  which an endpoint can operate (e.g.  Provisioning Domain (PvD) information RFC7556);

Reviewer comments:
This tries to write something small but specific about Network Policies
LGTM
In Sec 2: Should Section 3.2 also talk about network policies, e.g. a certain network supports a DSCP that the application desires?
As discussed in Feb 2021 interim, this seems like a rabbithole. Gorry will figure out whether it is and write language if not, or close if so.
I'd like to add a couple of lines of text here to bullet 2 that discusses how you might learn that an attached network supports certain features - e.g. through a PvD, routing advertisement, or local discovery method, and suggest that this could enable a system to know which paths have specific characteristics.
I propose this as a starter: When additional information (such as Provisioning Domain (PvD) information {{RFC7556}}) is provided about the networks over which an endpoint can operate, this can inform the selection between alternate network paths. Such information includes network segment PMTU, set of supported DSCPs, expected usage, cost, etc. The usage of this information by the Transport Services API is generally independent of the specific mechanism/protocol that was used to receive the information (e.g. zero-conf, DHCP, or IPv6 RA). Thoughts... ?
Tried to create a PR to add some policy to the path selection
I think the policy is separate from the API.LGTM

Revised text:
transport layer, in line with developments in modern platforms and programming languages;  <ins> Selection between alternate network paths that can be informed when additional information is available about the networks over </ins> which an endpoint can operate (e.g.  Provisioning Domain (PvD) information RFC7556);
Original text:
"Connection Priority" on one Connection does not change it on the other Connections in the same Connection Group. <del> Message Properties are also not entangled.  For example, changing "Lifetime" (see msg-lifetime) of a Message will only affect a single Message on a single Connection. </del>  A new Connection created by Clone can have a Message Framer assigned via the optional "framer" parameter of the Clone Action.  If this

Reviewer comments:
Applied requested changes
In 3.2 it is clear that you can set Message Properties on Connections and Preconnections, but the rest of the document is not very clear about this. In 4.2 for instance the text only talks about setting Selection Properties and Connection Properties on PreConnections. In 7.1.3 the text says "Connection Properties describe the default behavior for all Messages on a Connection". But I think that Message Properties set on a Connection or PreConnection may also describe the default behavior so this relationship should be clarified. Also, the Message Property defaults given for Properties that do not depend on other Properties sets the defaults for all Messages in a Connection I assume? I also assume that a Message Property set on a Message Context overrides a Message Property set on a PreConnection or Connection, but this is also not specified. In 5.4. Connection Groups, I assume that setting Message Properties on a Connection applies to all Connections in the Connection Group? This is not clear.
In general, I agree. If you set a message property dynamically on a connection, though, I don't think it would affect the group—I could have one stream in a multiplexed protocol have separate behavior, such as priority.
+1 to tfpauly. But this is already written in 5.4, maybe you missed it (Anna)? "Message Properties are also not entangled. For example, changing Lifetime (see Section 7.1.3.1) of a Message will only affect a single Message on a single Connection."
I am fine with an update of a Message Property to a connection applying only to that connection. Priority is not a good example as it is already a special case, but my main issue was that we need to be more clear about the behavior in the specification. NAME the issue is about setting a Message Property on a Connection. The text you refer to talk about setting Message Properties on a message. You could interpret the first part as a general statement, but the way the text is structured it is easy to think it refers to setting Message Properties on a message so I think we should be explicit also about setting Message Properties on a Connection. Could be a second example.
So after looking at the text again, I think the example talking about setting Message Properties on a message should be removed, see comment in the pull request.
Thanks!!

Revised text:
"Connection Priority" on one Connection does not change it on the other Connections in the same Connection Group.  <ins> Message Properties set on a Connection also apply only to that Connection. </ins> A new Connection created by Clone can have a Message Framer assigned via the optional "framer" parameter of the Clone Action.  If this
Original text:
IP address (IPv4 or IPv6 address): <del> Interface name (string): </del>  Note that an IPv6 address specified with a scope (e.g. "2001:db8:4920:e29d:a420:7461:7073:0a%en0") is equivalent to

Reviewer comments:
Explain the different use-cases on specifying interfaces to
There's something obvious I'm not seeing: if I want to specify a multicast or link-local address for an endpoint, why not simply specify that address? What's the use of adding the interface into it? Some addresses will inherently limit interfaces; I thought interface preference was about preferring wifi to 4G, etc.
Like, in section 6.1.1:
Multicast groups can be scoped (see RFC7346), thus, may only be available on certain interfaces or even have different meanings based on the interface. So for Interface- and Link-Local scope, specifying the interface is strictly required. For others use cases (like coping with non-unique use of RFC1918 addresses) this may also be helpful.
Why does the API have both the ability to say LocalSpecifier.WithInterface and to set interface requirements on TransportProperties? Why not just keep the latter and remove the former?
There's history here: LocalSpecifier.WithInterface predates explicitly setting the interface name in interface requirements. There might be reasons to keep this: LocalSpecifier is more likely to show up in application UI than in transport properties. Any text proposed to keep both would need to have an unambiguous way to resolve conflicts between the two. This might be a source of hard-to-debug errors.
To discuss next interim

Revised text:
IP address (IPv4 or IPv6 address):  <ins> Interface name (string), e.g., to qualify link-local or multicast addresses (see ifspec for details): </ins> Note that an IPv6 address specified with a scope (e.g. "2001:db8:4920:e29d:a420:7461:7073:0a%en0") is equivalent to
Original text:
6.1.2.  An Endpoint can have an alternative definition when using different protocols.  For example, a server that supports both TLS/TCP and QUIC may be accessible on two different port numbers depending on which

Reviewer comments:
Explain the different use-cases on specifying interfaces to
There's something obvious I'm not seeing: if I want to specify a multicast or link-local address for an endpoint, why not simply specify that address? What's the use of adding the interface into it? Some addresses will inherently limit interfaces; I thought interface preference was about preferring wifi to 4G, etc.
Like, in section 6.1.1:
Multicast groups can be scoped (see RFC7346), thus, may only be available on certain interfaces or even have different meanings based on the interface. So for Interface- and Link-Local scope, specifying the interface is strictly required. For others use cases (like coping with non-unique use of RFC1918 addresses) this may also be helpful.
Why does the API have both the ability to say LocalSpecifier.WithInterface and to set interface requirements on TransportProperties? Why not just keep the latter and remove the former?
There's history here: LocalSpecifier.WithInterface predates explicitly setting the interface name in interface requirements. There might be reasons to keep this: LocalSpecifier is more likely to show up in application UI than in transport properties. Any text proposed to keep both would need to have an unambiguous way to resolve conflicts between the two. This might be a source of hard-to-debug errors.
To discuss next interim

Revised text:
6.1.2. <ins> Note that this API has multiple ways to constrain and prioritize endpoint candidates based on the network interface: Specifying an interface on a RemoteEndpoint qualifies the scope of the remote endpoint, e.g., for link-local addresses. Specifying an interface on a LocalEndpoint explicitly binds all candidates derived from this endpoint to use the specified interface. Specifying an interface using the "interface" Selection Property (prop-interface) or indirectly via the "pvd" Selection Property (prop-pvd) influences the selection among the available candidates. While specifying an interface on an endpoint restricts the candidates available for connection establishment in the Pre-Establishment Phase, the Selection Properties prioritize and constrain the connection establishment. 6.1.3. </ins> An Endpoint can have an alternative definition when using different protocols.  For example, a server that supports both TLS/TCP and QUIC may be accessible on two different port numbers depending on which