jiebi/CodeConvo huggingface dataset:
Change:
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.

Discussion:
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> <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
Change:
This attempts to clarify transport segmentation (a sparate PR will propose to clarify Frag)
Closing Set part of the Frag story

Discussion:
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> <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 <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> <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
Change:
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

Discussion:
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> <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-
Change:
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

Discussion:
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> <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.
Change:
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

Discussion:
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> <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.
Change:
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.

Discussion:
4.2.7. <del> perMsgChecksumSend </del> <ins> FullChecksumSend </ins> Preference

4.2.8. <del> perMsgChecksumRecv </del> <ins> FullChecksumRecv </ins> Preference
Change:
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.

Discussion:
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> <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
Change:
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.

Discussion:
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> <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.
Change:
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!

Discussion:
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> <ins> Capacity-Seeking: Prefer adapting to paths to determine the </ins> highest available capacity, based on the observed maximum throughput.
Change:
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)

Discussion:
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> <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.
Change:
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).

Discussion:
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> <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
Change:
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

Discussion:
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> <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
Change:
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

Discussion:
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> <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 <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> <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
Change:
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

Discussion:
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
Change:
Describe what you mean by racing earlier in the document - the use in the Introduction is bare.
As NAME said.

Discussion:
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> <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
Change:
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?

Discussion:
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
Change:
The concept of cloning is used in the overview without introduction. I've suggested an earlier discussion of it in the architecture document, which would help, but even in this document, there should be an introduction or forward reference.

Discussion:
Explicit support for multistreaming and multipath transport protocols, and the grouping of related Connections into Connection <del> Groups through cloning of Connections.  This allows applications to take full advantage of new transport protocols supporting these features. </del> <ins> Groups through "cloning" of Connections (see groups).  This function allows applications to take full advantage of new transport protocols supporting these features. </ins> 3.
Change:
Note that this PR does not say only the following characters are allowed... it just lists some that are allowed.
At the discussion of Transport Property Names at 4.1, I think you need to be more specific than "alphanumeric". Explicitly list what characters are allowed.
Since we've overspecified already: [A-Za-z0-9_]
Or go back to underspecifying: say they're human-readable textual labels that have namespaces, and don't specify the syntax of exactly how that namespacing works.

Discussion:
Transport Properties are referred to by property names.  For the purposes of this document, these names are alphanumeric strings in <del> which words may be separated by hyphens.  These names serve two purposes: </del> <ins> which words may be separated by hyphens.  Specifically, the following characters are allowed: lowercase letters "a-z", uppercase letters "A-Z", digits "0-9", the hyphen "-", and the underscore "_".  These names serve two purposes: </ins> Allowing different components of a TAPS implementation to pass Transport Properties, e.g., between a language frontend and a
Change:
At 8.1.2 you say lower values have higher priorities for connPrio. But later, at msgPrio, higher values have higher priority, and in the examples where you speak of the interaction of connPrio and msgPrio, you imply that higher means higher for both properties. Please check for consistency and clarify.
Lower values having higher priorities for connPrio is a remnant that we must have missed when we flipped this, e.g. PR which I don't know... too many iterations have mangled the text.
Aha, now I see what happened: following some more PRs, also , in PR , NAME re-introduced some text saying that sends on Connections with lower-priority values will be prioritized over sends on Connections with a higher-priority value. This reverses the logic for some part of the text - I suspect that NAME (very understandably!) forgot what happened and this created this mix. We have been editing these documents for way too long!
LGTM.

Discussion:
The "Connection Priority" Connection Property operates on Connections in a Connection Group using the same approach as in msg-priority: when allocating available network capacity among Connections in a <del> Connection Group, sends on Connections with lower Priority values will be prioritized over sends on Connections with higher Priority values.  Capacity will be shared among these Connections according to the Connection Group Transmission Scheduler property (conn- scheduler).  See priority-in-taps for more. </del> <ins> Connection Group, sends on Connections with higher Priority values will be prioritized over sends on Connections that have lower Priority values.  Capacity will be shared among these Connections according to the Connection Group Transmission Scheduler property (conn-scheduler).  See priority-in-taps for more. </ins> 8.

100 <del> This Property is a non-negative integer representing the relative inverse priority (i.e., a lower value reflects a higher priority) of </del> <ins> This Property is a non-negative integer representing the priority of </ins> this Connection relative to other Connections in the same Connection <del> Group.  It has no effect on Connections not part of a Connection Group.  As noted in groups, this property is not entangled when Connections are cloned, i.e., changing the Priority on one Connection in a Connection Group does not change it on the other Connections in the same Connection Group.  No guarantees of a specific behavior regarding Connection Priority are given; a Transport Services system may ignore this property.  See priority-in-taps for more details. </del> <ins> Group.  A higher value reflects a higher priority.  It has no effect on Connections not part of a Connection Group.  As noted in groups, this property is not entangled when Connections are cloned, i.e., changing the Priority on one Connection in a Connection Group does not change it on the other Connections in the same Connection Group. No guarantees of a specific behavior regarding Connection Priority are given; a Transport Services system may ignore this property.  See priority-in-taps for more details. </ins> 8.1.3.