jiebi/TextFlow huggingface dataset:
Original text:
example, if an application indicates a preference for a specific path by specifying an interface, but also a preference for a protocol, a situation might occur in which the preferred protocol is not <del> available on the preferred path.  In such cases, implementations SHOULD prioritize Selection Properties that select paths over those that select protocols.  Therefore, the transport system SHOULD race the path first, ignoring the protocol preference if a specific protocol does not work on the path. </del>  Selection and Connection Properties, as well as defaults for Message Properties, can be added to a Preconnection to configure the

Reviewer comments:
Section 4.2: " In such cases, implementations SHOULD prioritize Selection Properties that select paths over those that select protocols." I think I agree to this recommendation but it comes a little out of nowhere and we should probably provide some reasoning, especially as this is normative.
Proposing to change text to address the application developer: to expect that the path selection properties would be preferred over protocol selection properties. We should also explain a bit of the rationale, to explain that path properties are generally more sensitive around policy/expense.

Revised text:
example, if an application indicates a preference for a specific path by specifying an interface, but also a preference for a protocol, a situation might occur in which the preferred protocol is not  <ins> available on the preferred path.  In such cases, applications can expect properties that determine path selection to be prioritized over properties that determine protocol selection.  The transport system SHOULD determine the preferred path first, regardless of protocol preferences.  This ordering is chosen to provide consistency across implementations, based on the fact that it is more common for the use of a given network path to determine cost to the user (i.e., an interface type preference might be based on a user's preference to avoid being charged more for a cellular data plan). </ins> Selection and Connection Properties, as well as defaults for Message Properties, can be added to a Preconnection to configure the
Original text:
Integer This property, if applicable, represents the maximum Message size <del> that can be sent without incurring network-layer fragmentation or transport layer segmentation at the sender.  It exposes the Maximum Packet Size (MPS) as described in Datagram PLPMTUD RFC8899. </del>  6.1.11.3. false <del> When set to true, this property requests the network layer at the sending endpoint to not fragment the packets generated by the transport layer.  When running over IPv4, setting this property to true will also cause the Don't Fragment bit to be set in the IP header.  When this property is set, an attempt to send a message size </del>  greater than the transport's current estimate of its maximum packet size (singularTransmissionMsgMaxLen) will result in a SendError. This only takes effect when the transport and network layer support

Reviewer comments:
This attempts to clarify transport segmentation (a sparate PR will propose to clarify Frag)
Closing Set part of the Frag story

Revised text:
Integer This property, if applicable, represents the maximum Message size  <ins> that can be sent without incurring network-layer fragmentation at the sender.  It exposes a value to the application based on the Maximum Packet Size (MPS) as described in Datagram PLPMTUD RFC8899.  This can allow a sending stack to avoid unwanted fragmentation at the network- layer or segmentation by the transport layer. </ins> 6.1.11.3. false  <ins> When set to true, this property requests the transport layer to not provide segmentation of messages larger than the maximum size permitted by the network layer, and also to avoid network-layer source fragmentation of messages.  When running over IPv4, setting this property to true can result in a sending endpount setting the Don't Fragment bit in the IPv4 header of packets generated by the transport layer.  An attempt to send a message that results in a size </ins> greater than the transport's current estimate of its maximum packet size (singularTransmissionMsgMaxLen) will result in a SendError. This only takes effect when the transport and network layer support
Original text:
An application primarily interacts with this API through two Objects: Preconnections and Connections.  A Preconnection represents a set of properties and constraints on the selection and configuration of <del> paths and protocols to establish a Connection with a Endpoint.  A </del>  Connection represents an instance of a transport Protocol Stack on which data can be sent to and/or received from a Remote Endpoint (i.e., depending on the kind of transport, connections can be bi-

Reviewer comments:
The use of “remote” on its own offends me: “Some types of remote might …” could we make this “Remote Endpoint” to ease my reading? or whatever else is intended? Similarly can we change “locals” and “remote” here to something that is defined: “This can expose some or all of the candidate locals to the remote”
Remote Endpoint

Revised text:
An application primarily interacts with this API through two Objects: Preconnections and Connections.  A Preconnection represents a set of properties and constraints on the selection and configuration of  <ins> paths and protocols to establish a Connection with an Endpoint.  A </ins> Connection represents an instance of a transport Protocol Stack on which data can be sent to and/or received from a Remote Endpoint (i.e., depending on the kind of transport, connections can be bi-
Original text:
Listen: Enables a listener to accept incoming Connections.  The Listener will then create Connection objects as incoming connections are accepted (events).  Listeners by default register <del> with multiple paths, protocols, and local endpoints, unless </del>  constrained by Selection Properties and/or the specified Local Endpoint(s).  Connections can be accepted on any of the available paths or endpoints.

Reviewer comments:
NiT
Part of Issue
Merged
The use of “remote” on its own offends me: “Some types of remote might …” could we make this “Remote Endpoint” to ease my reading? or whatever else is intended? Similarly can we change “locals” and “remote” here to something that is defined: “This can expose some or all of the candidate locals to the remote”
Remote Endpoint

Revised text:
Listen: Enables a listener to accept incoming Connections.  The Listener will then create Connection objects as incoming connections are accepted (events).  Listeners by default register  <ins> with multiple paths, protocols, and Local Endpoints, unless </ins> constrained by Selection Properties and/or the specified Local Endpoint(s).  Connections can be accepted on any of the available paths or endpoints.
Original text:
The process of connection establishment completes when one leaf node of the tree has successfully completed negotiation with the Remote <del> Endpoint , or else all nodes of the tree have failed to connect.  The </del>  first leaf node to complete its connection is then used by the application to send and receive data.

Reviewer comments:
Trying to address use of “remote” and "local"
The use of “remote” on its own offends me: “Some types of remote might …” could we make this “Remote Endpoint” to ease my reading? or whatever else is intended? Similarly can we change “locals” and “remote” here to something that is defined: “This can expose some or all of the candidate locals to the remote”
Remote Endpoint

Revised text:
The process of connection establishment completes when one leaf node of the tree has successfully completed negotiation with the Remote  <ins> Endpoint, or else all nodes of the tree have failed to connect.  The </ins> first leaf node to complete its connection is then used by the application to send and receive data.
Original text:
4.2.7. <del> perMsgChecksumSend </del>  Preference 4.2.8. <del> perMsgChecksumRecv </del>  Preference

Reviewer comments:
Why is the name not rather something like perMsgChecksumFullSend?
Happy with a change if making this more consistent.
There are some related changes in
NAME : Did the merged PR 839 happen to address this? - If not please make a PR.
NAME PR 839 updated the name, but still found it confusing so made a PR.
See review.
I do not mind what the name is called as long as it is clear. I think the proposal looks good.

Revised text:
4.2.7.  <ins> FullChecksumSend </ins> Preference 4.2.8.  <ins> FullChecksumRecv </ins> Preference
Original text:
A request by an application for Protocol Properties that include requirements or prohibitions that cannot be satisfied by any of the available protocols.  For example, if an application requires <del> "Configure Reliability per Message", but no such protocol is available on the host running the transport system this should result in an error, e.g., when SCTP is not supported by the operating system. </del>  A request by an application for Protocol Properties that are in conflict with each other, i.e., the required and prohibited

Reviewer comments:
Nit: Section 3.1: No such protocol…
I’ll argue this “but no such protocol is available on the host running the transport system” is asking for a feature, so I think the text ought to read: “but no such feature is available in any protocol the host running the transport system”
"but no protocol available on the host offers such a feature"
This was fixed in the already merged PR.

Revised text:
A request by an application for Protocol Properties that include requirements or prohibitions that cannot be satisfied by any of the available protocols.  For example, if an application requires  <ins> "Configure Reliability per Message", but no such feature is available in any protocol the host running the transport system on the host running the transport system this should result in an error, e.g., when SCTP is not supported by the operating system. </ins> A request by an application for Protocol Properties that are in conflict with each other, i.e., the required and prohibited
Original text:
even if the Advertisement of Alternative Addresses property (see altaddr below) is set to false. <del> Enumeration values other than "Disabled" are interpreted as a preference for choosing protocols that can make use of multiple paths.  The "Disabled" value implies a requirement not to use multiple paths in parallel but does not prevent choosing a protocol that is capable of using multiple paths, e.g., it does not prevent choosing TCP, but prevents sending the "MP_CAPABLE" option in the TCP handshake. </del>  4.2.15.

Reviewer comments:
I know we have discussed Multipath Transport many times, but when reading is seems strange when you get to Multipath Transport and here there is no option to "Require" this property, only to "Prefer" it. We should at least say why. It is perhaps intuitive that you do not need to distinguish between Avoid and Prohibit, but not why Require would not be useful.
Add a sentence after this to explain why "require" wouldn't make sense:
This reflects what we agreed on, during the last interim.

Revised text:
even if the Advertisement of Alternative Addresses property (see altaddr below) is set to false.  <ins> Note that Multipath Transport has no corresponding Selection Property of type Preference.  Enumeration values other than "Disabled" are interpreted as a preference for choosing protocols that can make use of multiple paths.  The "Disabled" value implies a requirement not to use multiple paths in parallel but does not prevent choosing a protocol that is capable of using multiple paths, e.g., it does not prevent choosing TCP, but prevents sending the "MP_CAPABLE" option in the TCP handshake. </ins> 4.2.15.
Original text:
satisy the requested Stream Send or Stream Receive Bitrate, based on the observed maximum throughput; <del> Capacity-Seeking: Prefer adpating to paths to determine the </del>  highest available capacity, based on the observed maximum throughput.

Reviewer comments:
This is a first cut, I'll update next.
The Capacity Profile in the API draft (now) lists these possible choices: Default, Scavenger, Low Latency/Interactive, Low Latency/Non-Interactive, Constant-Rate Streaming and Capacity-Seeking. The text in section 4.1.3 only discusses Scavenger, Low Latency/Interactive, and Constant-Rate Streaming.
Aha - I could offer to align the Capacity Profile classes?
See a PR to align Capacity profile with API
Resolved
LGTM, thanks!

Revised text:
satisy the requested Stream Send or Stream Receive Bitrate, based on the observed maximum throughput;  <ins> Capacity-Seeking: Prefer adapting to paths to determine the </ins> highest available capacity, based on the observed maximum throughput.
Original text:
defines the concepts that are used by both the API and implementation documents.  The Preconnection allows applications to configure Connection Properties, and the Connection represents <del> an object that can be used to send and receive Messages.  A connection is a local operation that serves to simplify the local send/receive functions and to filter the traffic for the endpoint. This might (as in TCP) or might not (as in UDP) represent an end- to-end protocol connection across the network path. </del>  1.3.

Reviewer comments:
Added a couple of sentences to Arch that are hoped to early introduce that connections are things in the API, not aretfacts of the transport protocol instances. Different to, but related to an issue for the description in API.
"A is an abstraction that represents the communication. If the transport services interface selects a protocol such as TCP for the communication, a will correspond to an underlying protocol connection. In the other hand, if a protocol such as UDP is selected, the remains an abstraction in the end points and doesn't correspond to explicit protocol state" ?
NAME : Could you live with the update in this PR?
yes, I think so (assuming I'm reading the diff right)

Revised text:
defines the concepts that are used by both the API and implementation documents.  The Preconnection allows applications to configure Connection Properties, and the Connection represents  <ins> an object that can be used to send and receive Messages. A Connection is an abstraction that represents the communication. If the transport services interface selects a protocol such as TCP for the communication, a Connection will correspond to an underlying protocol connection.  If however a protocol such as UDP is selected, the Connection remains an abstraction at the end points. </ins> 1.3.
Original text:
For Connections that are Established or Closing: Transport Properties that the application specified on the Preconnection. Selection Properties indicate whether or not the Connection has or <del> offers a certain Selection Property, see selection-props </del>  The actually instantiated protocol stack might not match all Protocol Selection Properties that the application specified on the Preconnection.  For example, a certain Protocol Selection

Reviewer comments:
In response to ... This moves the discussion of protocol instances into bullet 4, and the properties (mainly selection) into bullet 5. It does not intend to change any text, and is intended to avoid what appeared to be overlap.
Resolved issue following MW review
I do not understand the relationship between bullets four and five. They seem to overlap?
NAME : Anna, is this resolved by this PR: Re-group managing properties & protocol instances ?
LGTM, but note that I marked a nit (missing full stop).

Revised text:
For Connections that are Established or Closing: Transport Properties that the application specified on the Preconnection. Selection Properties indicate whether or not the Connection has or  <ins> offers a certain Selection Property, see selection-props. </ins> The actually instantiated protocol stack might not match all Protocol Selection Properties that the application specified on the Preconnection.  For example, a certain Protocol Selection
Original text:
DTLS session, a SCTP stream, a QUIC stream, or an HTTP/2 stream). The properties held by a Connection or Listener is independent of other connections that are not part of the same Connection Group. <del> Once Initate has been called, the Selection Properties and Endpoint </del>  information are immutable (i.e, an application is not able to later modify Selection Properties on the original Preconnection object). Listener objects are created with a Preconnection, at which point

Reviewer comments:
Added something directly from RFC8085 that UDP can be connected in a sense.
If this is any help, RFC8085 said: "Many operating systems also allow a UDP socket to be connected, i.e., to bind a UDP socket to a specific pair of addresses and ports. This is similar to the corresponding TCP sockets API functionality. However, for UDP, this is only a local operation that serves to simplify the local send/receive functions and to filter the traffic for the specified addresses and ports."
Added text in

Revised text:
DTLS session, a SCTP stream, a QUIC stream, or an HTTP/2 stream). The properties held by a Connection or Listener is independent of other connections that are not part of the same Connection Group.  <ins> Connection establishment is only a local operation for a Datagram transport (e.g., UDP(-Lite)), which serves to simplify the local send/receive functions and to filter the traffic for the specified addresses and ports RFC8085. Once Initiate has been called, the Selection Properties and Endpoint </ins> information are immutable (i.e, an application is not able to later modify Selection Properties on the original Preconnection object). Listener objects are created with a Preconnection, at which point
Original text:
4.1.2. Preconnection: A Preconnection object is a representation of a <del> potential Connection.  It has state that describes parameters of a Connection that might exist in the future: the Local Endpoint from </del>  which that Connection will be established, the Remote Endpoint (preestablishment) to which it will connect, and Transport Properties that influence the paths and protocols a Connection <del> will use.  A Preconnection can be fully specified such that it represents a single possible Connection, or it can be partially specified such that it represents a family of possible Connections.  The Local Endpoint (preestablishment) is required if the Preconnection is used to Listen for incoming Connections.  The Local Endpoint is optional if it is used to Initiate Connections. The Remote Endpoint is required in the Preconnection that is used to Initiate Connections.  The Remote Endpoint is optional if it is used to Listen for incoming Connections.  The Local Endpoint and the Remote Endpoint are both required if a peer-to-peer Rendezvous is to occur based on the Preconnection. </del>  Transport Properties: Transport Properties allow the application to express their requirements, prohibitions, and preferences and

Reviewer comments:
Gorry's attempt to improve preconnection ()
The big paragraph that is the first bullet of section 4.1.2 doesn't read well. Pleas consider restructuring it, and simplifying the sentences as much as possible.
I think this reads better

Revised text:
4.1.2. Preconnection: A Preconnection object is a representation of a  <ins> Connection that has not yet been established.  It has state that describes parameters of the Connection: the Local Endpoint from </ins> which that Connection will be established, the Remote Endpoint (preestablishment) to which it will connect, and Transport Properties that influence the paths and protocols a Connection  <ins> will use.  A Preconnection can be either fully specified (representing a single possible Connection), or it can be partially specified (representing a family of possible Connections).  The Local Endpoint (preestablishment) is required for a Preconnection used to Listen for incoming Connections, but optional if it is used to Initiate a Connection.  The Remote Endpoint is required in a Preconnection that used to Initiate a Connection, but is optional if it is used to Listen for incoming Connections.  The Local Endpoint and the Remote Endpoint are both required if a peer-to-peer Rendezvous is to occur based on the Preconnection. </ins> Transport Properties: Transport Properties allow the application to express their requirements, prohibitions, and preferences and
Original text:
Message Framer, all bytes received on the Connection will be represented as one large Message of indeterminate length.  9.3.2.3. A ReceiveError occurs when data is received by the underlying

Reviewer comments:
Reading 7.3.2 I found the concepts there quite abstract. I think it would really help to be a bit more specific and e.g. take UDP and TCP as examples basically saying some like: as UDP is consider a message based protocol, each received datagram will trigger receive() of a complete message. As TCP is stream-based all TCP segments will be delivered by ReceivedPartial().
My impression here is that we could use some examples for different protocols for sending and receiving (for messages, datagrams, and raw streams). This could be a 7.4 Examples section.
Do we need to do this - can we just close this?
I think it's still valuable to have an example of ReceivedPartial somewhere.
The ReceivedPartial example is good. I think we may need clarification that Received can support object-based rather than just byte-array-based responses.
LGMT

Revised text:
Message Framer, all bytes received on the Connection will be represented as one large Message of indeterminate length. <ins> In the following example, an application only wants to receive up to 1000 bytes at a time from a Connection.  If a 1500-byte message arrives, it would receive the message in two separate ReceivedPartial events. </ins> 9.3.2.3. A ReceiveError occurs when data is received by the underlying
Original text:
application requirements and network conditions, without requiring changes to the applications.  This flexibility enables faster deployment of new features and protocols.  It can also support <del> applications by offering racing and fallback mechanisms, which otherwise need to be implemented in each application separately. </del>  This document was developed in parallel with the specification of the Transport Services API I-D.ietf-taps-interface and Implementation

Reviewer comments:
Describe what you mean by racing earlier in the document - the use in the Introduction is bare.
As NAME said.

Revised text:
application requirements and network conditions, without requiring changes to the applications.  This flexibility enables faster deployment of new features and protocols.  It can also support  <ins> applications by offering racing mechanisms (attempting multiple IP addresses, protocols, or network paths in parallel), which otherwise need to be implemented in each application separately (see racing). </ins> This document was developed in parallel with the specification of the Transport Services API I-D.ietf-taps-interface and Implementation
Original text:
may have implementation-specific default handlers.  The application should not assume that ignoring Events (e.g., Errors) is always safe. <del> pre-establishment, establishment, sending, receiving, and termination describe the details of application interaction with Objects through Actions and Events in each phase of a Connection, following the phases (Pre-Establishment, Establishment, Data Transfer, and Termination) described in Section 4.1 of I-D.ietf-taps-arch. </del> 3.1. The following usage examples illustrate how an application might use

Reviewer comments:
At the end of the API summary, there's a paragraph that looks like a "Structure of this document" discussion - should it be in a different place? The list in the paragraph is odd - why is Section 8, for instance, not in the list?

Revised text:
may have implementation-specific default handlers.  The application should not assume that ignoring Events (e.g., Errors) is always safe.  3.1. The following usage examples illustrate how an application might use