From f7b1d998a667ed3f006d42d284add228044275b4 Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Wed, 3 Sep 2025 14:04:35 -0600
Subject: [PATCH 01/15] don't append duplicate metdata

---
 source/mongodb-handshake/handshake.md    | 15 ++++--
 source/mongodb-handshake/tests/README.md | 60 ++++++++++++++++++++++++
 2 files changed, 72 insertions(+), 3 deletions(-)

diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md
index aa5574718e..fd63bba760 100644
--- a/source/mongodb-handshake/handshake.md
+++ b/source/mongodb-handshake/handshake.md
@@ -185,8 +185,8 @@ Drivers MUST NOT provide a default value for this key.
 
 This value is required and is not application configurable.
 
-The internal driver name. For drivers written on-top of other core drivers, the underlying driver will typically expose
-a function to append additional name to this field.
+The internal driver name. For drivers written on-top of other core drivers, the `appendClientMetadata()` method can be
+used to add package information to an existing MongoClient.
 
 Example:
 
@@ -200,7 +200,7 @@ Example:
 This value is required and is not application configurable.
 
 The internal driver version. The version formatting is not defined. For drivers written on-top of other core drivers,
-the underlying driver will typically expose a function to append additional name to this field.
+the `appendClientMetadata()` method can be used to add package information to an existing MongoClient.
 
 Example:
 
@@ -405,6 +405,9 @@ class DriverInfoOptions {
 }
 ```
 
+Two `DriverInfo` objects are considered identical if all fields are strictly equal with case sensitive string
+comparison.
+
 Note that how these options are provided to a driver during `MongoClient` initialization is left up to the implementer.
 
 ### Metadata updates after MongoClient initialization
@@ -442,6 +445,12 @@ be appended to their respective fields, and be delimited by a `|` character. For
 }
 ```
 
+Some client libraries provide APIs that accept a pre-initialized MongoClient as an argument. In these circumstances, it
+is possible for multiple library objects to be associated with the same MongoClient, which could result in the same
+metadata being appended multiple times. Drivers MUST ensure that a `DriverInfo` object can be appended to a MongoClient
+exactly once. However, drivers MUST ensure that the same `name` with different versions or platforms can be appended to
+the existing MongoClient object.
+
 **NOTE:** All strings provided as part of the driver info MUST NOT contain the delimiter used for metadata concatention.
 Drivers MUST throw an error if any of these strings contains that character.
 
diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md
index 848c6351fd..6a8b0ef302 100644
--- a/source/mongodb-handshake/tests/README.md
+++ b/source/mongodb-handshake/tests/README.md
@@ -207,3 +207,63 @@ Before each test case, perform the setup.
             - Otherwise, the field remains unchanged: `Library Platform`
 
     - All other subfields in the `client` document remain unchanged from `updatedClientMetadata`.
+
+## Test 3: Multiple Successive Metadata Updates with Identical/Partially Identical `DriverInfo`
+
+There are multiple test cases parameterized with `DriverInfoOptions` to be appended after a previous metadata update.
+Before each test case, perform the setup.
+
+### Setup
+
+1. Create a `MongoClient` instance with:
+
+    - `maxIdleTimeMS` set to `1ms`
+
+2. Append the following `DriverInfoOptions` to the `MongoClient` metadata:
+
+    | Field    | Value            |
+    | -------- | ---------------- |
+    | name     | library          |
+    | version  | 1.2              |
+    | platform | Library Platform |
+
+3. Send a `ping` command to the server and verify that the command succeeds.
+
+4. Save intercepted `client` document as `updatedClientMetadata`.
+
+5. Wait 5ms for the connection to become idle.
+
+#### Parameterized test cases
+
+| Case | Name      | Version | Platform           |
+| ---- | --------- | ------- | ------------------ |
+| 1    | library   | 1.2     | Library Platform   |
+| 2    | framework | 1.2     | Library Platform   |
+| 3    | library   | 2.0     | Library Platform   |
+| 4    | library   | 1.2     | Framework Platform |
+| 5    | framework | 2.0     | Library Platform   |
+| 7    | framework | 1.2     | Framework Platform |
+| 8    | library   | 2.0     | Framework Platform |
+
+#### Running a test case
+
+1. Append the `DriverInfoOptions` from the selected test case to the `MongoClient` metadata.
+
+2. Send a `ping` command to the server and verify:
+
+    - The command succeeds.
+
+    - The framework metadata is appended to the existing `DriverInfoOptions` in the `client.driver` fields of the `hello`
+        command, with values separated by a pipe `|`.
+
+        - `client.driver.name`:
+            - If test case's name is `framework`: `library|framework`
+            - Otherwise, the field remains unchanged: `library`
+        - `client.driver.version`:
+            - If test case's version is 2.0: `1.2|2.0`
+            - Otherwise, the field remains unchanged: `1.2`
+        - `client.driver.platform`:
+            - If test case's platform is `Framework Platform`: `Library Platform|Framework Platform`
+            - Otherwise, the field remains unchanged: `Library Platform`
+
+    - All other subfields in the `client` document remain unchanged from `updatedClientMetadata`.

From 8df931748a09f591540a4483dfbefa39a3d40bbc Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Wed, 3 Sep 2025 14:06:09 -0600
Subject: [PATCH 02/15] fix method name

---
 source/mongodb-handshake/handshake.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md
index fd63bba760..35de64183a 100644
--- a/source/mongodb-handshake/handshake.md
+++ b/source/mongodb-handshake/handshake.md
@@ -185,8 +185,8 @@ Drivers MUST NOT provide a default value for this key.
 
 This value is required and is not application configurable.
 
-The internal driver name. For drivers written on-top of other core drivers, the `appendClientMetadata()` method can be
-used to add package information to an existing MongoClient.
+The internal driver name. For drivers written on-top of other core drivers, the `appendMetadata()` method can be used to
+add package information to an existing MongoClient.
 
 Example:
 
@@ -200,7 +200,7 @@ Example:
 This value is required and is not application configurable.
 
 The internal driver version. The version formatting is not defined. For drivers written on-top of other core drivers,
-the `appendClientMetadata()` method can be used to add package information to an existing MongoClient.
+the `appendMetadata()` method can be used to add package information to an existing MongoClient.
 
 Example:
 

From 6cf6071714f5cd187f03fd4658b8806d86648c96 Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Wed, 3 Sep 2025 14:07:11 -0600
Subject: [PATCH 03/15] equality name

---
 source/mongodb-handshake/handshake.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md
index 35de64183a..eaf3ee40f3 100644
--- a/source/mongodb-handshake/handshake.md
+++ b/source/mongodb-handshake/handshake.md
@@ -405,7 +405,7 @@ class DriverInfoOptions {
 }
 ```
 
-Two `DriverInfo` objects are considered identical if all fields are strictly equal with case sensitive string
+Two `DriverInfoOptions` objects are considered identical if all fields are strictly equal with case sensitive string
 comparison.
 
 Note that how these options are provided to a driver during `MongoClient` initialization is left up to the implementer.

From 0eb447c77ffe0959b7a043339df1081417259500 Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Wed, 3 Sep 2025 14:07:45 -0600
Subject: [PATCH 04/15] phrasing

---
 source/mongodb-handshake/handshake.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md
index eaf3ee40f3..0a1c6947a2 100644
--- a/source/mongodb-handshake/handshake.md
+++ b/source/mongodb-handshake/handshake.md
@@ -448,8 +448,7 @@ be appended to their respective fields, and be delimited by a `|` character. For
 Some client libraries provide APIs that accept a pre-initialized MongoClient as an argument. In these circumstances, it
 is possible for multiple library objects to be associated with the same MongoClient, which could result in the same
 metadata being appended multiple times. Drivers MUST ensure that a `DriverInfo` object can be appended to a MongoClient
-exactly once. However, drivers MUST ensure that the same `name` with different versions or platforms can be appended to
-the existing MongoClient object.
+exactly once.
 
 **NOTE:** All strings provided as part of the driver info MUST NOT contain the delimiter used for metadata concatention.
 Drivers MUST throw an error if any of these strings contains that character.

From 825d41fd0c9f852ae927fc3a9199655b3f2b2b09 Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Wed, 3 Sep 2025 14:14:17 -0600
Subject: [PATCH 05/15] add edge case

---
 source/mongodb-handshake/tests/README.md | 34 ++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md
index 6a8b0ef302..e4703e0691 100644
--- a/source/mongodb-handshake/tests/README.md
+++ b/source/mongodb-handshake/tests/README.md
@@ -244,6 +244,7 @@ Before each test case, perform the setup.
 | 5    | framework | 2.0     | Library Platform   |
 | 7    | framework | 1.2     | Framework Platform |
 | 8    | library   | 2.0     | Framework Platform |
+| 9    | framework | 2.0     | Framework Platform |
 
 #### Running a test case
 
@@ -267,3 +268,36 @@ Before each test case, perform the setup.
             - Otherwise, the field remains unchanged: `Library Platform`
 
     - All other subfields in the `client` document remain unchanged from `updatedClientMetadata`.
+
+## Test 4: Metadata is not appended if identical to initial metadata
+
+1. Create a `MongoClient` instance with:
+
+    - `maxIdleTimeMS` set to `1ms`
+    - `driverInfo` set to the following:
+
+    | Field    | Value            |
+    | -------- | ---------------- |
+    | name     | library          |
+    | version  | 1.2              |
+    | platform | Library Platform |
+
+2. Send a `ping` command to the server and verify that the command succeeds.
+
+3. Save intercepted `client` document as `clientMetadata`.
+
+4. Wait 5ms for the connection to become idle.
+
+5. Append the following `DriverInfoOptions` to the `MongoClient` metadata:
+
+    | Field    | Value            |
+    | -------- | ---------------- |
+    | name     | library          |
+    | version  | 1.2              |
+    | platform | Library Platform |
+
+6. Send a `ping` command to the server and verify that the command succeeds.
+
+7. Save intercepted `client` document as `updatedClientMetadata`.
+
+8. Assert that `clientMetadata` is identical to `updatedClientMetadata`.

From 624166595043bfd9389f72ec4fea93613be9abc3 Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Thu, 4 Sep 2025 11:59:58 -0600
Subject: [PATCH 06/15] Fix tests and update changelog

---
 source/mongodb-handshake/handshake.md    |  1 +
 source/mongodb-handshake/tests/README.md | 30 ++++++++++++------------
 2 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md
index 0a1c6947a2..445c12ba1b 100644
--- a/source/mongodb-handshake/handshake.md
+++ b/source/mongodb-handshake/handshake.md
@@ -561,6 +561,7 @@ support the `hello` command, the `helloOk: true` argument is ignored and the leg
 
 ## Changelog
 
+- 2025-09-04: Clarify that drivers do not append the same metadata multiple times.
 - 2025-06-09: Add requirement to allow appending to client metadata after `MongoClient` initialization.
 - 2024-11-05: Move handshake prose tests from spec file to prose test file.
 - 2024-10-09: Clarify that FaaS and container metadata must both be populated when both are present.
diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md
index e4703e0691..bce3bf2499 100644
--- a/source/mongodb-handshake/tests/README.md
+++ b/source/mongodb-handshake/tests/README.md
@@ -202,7 +202,7 @@ Before each test case, perform the setup.
         - `client.driver.version`:
             - If test case's version is non-null: `1.2|<version>`
             - Otherwise, the field remains unchanged: `1.2`
-        - `client.driver.platform`:
+        - `client.platform`:
             - If test case's platform is non-null: `Library Platform|<platform>`
             - Otherwise, the field remains unchanged: `Library Platform`
 
@@ -242,9 +242,9 @@ Before each test case, perform the setup.
 | 3    | library   | 2.0     | Library Platform   |
 | 4    | library   | 1.2     | Framework Platform |
 | 5    | framework | 2.0     | Library Platform   |
-| 7    | framework | 1.2     | Framework Platform |
-| 8    | library   | 2.0     | Framework Platform |
-| 9    | framework | 2.0     | Framework Platform |
+| 6    | framework | 1.2     | Framework Platform |
+| 7    | library   | 2.0     | Framework Platform |
+| 8    | framework | 2.0     | Framework Platform |
 
 #### Running a test case
 
@@ -255,17 +255,17 @@ Before each test case, perform the setup.
     - The command succeeds.
 
     - The framework metadata is appended to the existing `DriverInfoOptions` in the `client.driver` fields of the `hello`
-        command, with values separated by a pipe `|`.
-
-        - `client.driver.name`:
-            - If test case's name is `framework`: `library|framework`
-            - Otherwise, the field remains unchanged: `library`
-        - `client.driver.version`:
-            - If test case's version is 2.0: `1.2|2.0`
-            - Otherwise, the field remains unchanged: `1.2`
-        - `client.driver.platform`:
-            - If test case's platform is `Framework Platform`: `Library Platform|Framework Platform`
-            - Otherwise, the field remains unchanged: `Library Platform`
+        command, with values separated by a pipe `|`. To simplify assertions in these tests, strip out the default driver
+        info that is automatically added by the driver (ex: `metadata.name.split('|').slice(1).join('|')`).
+
+        - If the test case's DriverInfo is identical to the driver info from setup step 2 (test case 1):
+            - Assert metadata.name is equal to `library`
+            - Assert metadata.version is equal to `1.2`
+            - Assert metadata.platform is equal to `LibraryPlatform`
+        - Otherwise:
+            - Assert metadata.name is equal to `library|<name>`
+            - Assert metadata.version is equal to `1.2|<version>`
+            - Assert metadata.platform is equal to `LibraryPlatform|<platform>`
 
     - All other subfields in the `client` document remain unchanged from `updatedClientMetadata`.
 

From 997e0e7d6822d56f1797f6b7f6ae583455ddb227 Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Mon, 8 Sep 2025 11:15:58 -0600
Subject: [PATCH 07/15] Daria's comments

---
 source/mongodb-handshake/handshake.md    |  4 +-
 source/mongodb-handshake/tests/README.md | 95 +++++++++++++++++++++++-
 2 files changed, 95 insertions(+), 4 deletions(-)

diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md
index 445c12ba1b..cb8629a9fb 100644
--- a/source/mongodb-handshake/handshake.md
+++ b/source/mongodb-handshake/handshake.md
@@ -447,8 +447,8 @@ be appended to their respective fields, and be delimited by a `|` character. For
 
 Some client libraries provide APIs that accept a pre-initialized MongoClient as an argument. In these circumstances, it
 is possible for multiple library objects to be associated with the same MongoClient, which could result in the same
-metadata being appended multiple times. Drivers MUST ensure that a `DriverInfo` object can be appended to a MongoClient
-exactly once.
+metadata being appended multiple times. Drivers MUST ensure that a `DriverInfo` objects provided to a MongoClient or
+appended to a MongoClient are distinct (see [Supporting Wrapping Libraries](#supporting-wrapping-libraries)).
 
 **NOTE:** All strings provided as part of the driver info MUST NOT contain the delimiter used for metadata concatention.
 Drivers MUST throw an error if any of these strings contains that character.
diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md
index bce3bf2499..25b83b3d77 100644
--- a/source/mongodb-handshake/tests/README.md
+++ b/source/mongodb-handshake/tests/README.md
@@ -208,7 +208,7 @@ Before each test case, perform the setup.
 
     - All other subfields in the `client` document remain unchanged from `updatedClientMetadata`.
 
-## Test 3: Multiple Successive Metadata Updates with Identical/Partially Identical `DriverInfo`
+## Test 3: Multiple Successive Metadata Updates with Duplicate Data
 
 There are multiple test cases parameterized with `DriverInfoOptions` to be appended after a previous metadata update.
 Before each test case, perform the setup.
@@ -269,7 +269,53 @@ Before each test case, perform the setup.
 
     - All other subfields in the `client` document remain unchanged from `updatedClientMetadata`.
 
-## Test 4: Metadata is not appended if identical to initial metadata
+## Test 4: Multiple Metadata Updates with Duplicate Data
+
+1. Create a `MongoClient` instance with:
+
+    - `maxIdleTimeMS` set to `1ms`
+
+2. Append the following `DriverInfoOptions` to the `MongoClient` metadata:
+
+    | Field    | Value            |
+    | -------- | ---------------- |
+    | name     | library          |
+    | version  | 1.2              |
+    | platform | Library Platform |
+
+3. Send a `ping` command to the server and verify that the command succeeds.
+
+4. Wait 5ms for the connection to become idle.
+
+5. Append the following `DriverInfoOptions` to the `MongoClient` metadata:
+
+    | Field    | Value              |
+    | -------- | ------------------ |
+    | name     | framework          |
+    | version  | 2.0                |
+    | platform | Framework Platform |
+
+6. Send a `ping` command to the server and verify that the command succeeds.
+
+7. Save intercepted `client` document as `clientMetadata`.
+
+8. Wait 5ms for the connection to become idle.
+
+9. Append the following `DriverInfoOptions` to the `MongoClient` metadata:
+
+    | Field    | Value            |
+    | -------- | ---------------- |
+    | name     | library          |
+    | version  | 1.2              |
+    | platform | Library Platform |
+
+10. Send a `ping` command to the server and verify that the command succeeds.
+
+11. Save intercepted `client` document as `updatedClientMetadata`.
+
+12. Assert that `clientMetadata` is identical to `updatedClientMetadata`.
+
+## Test 5: Metadata is not appended if identical to initial metadata
 
 1. Create a `MongoClient` instance with:
 
@@ -301,3 +347,48 @@ Before each test case, perform the setup.
 7. Save intercepted `client` document as `updatedClientMetadata`.
 
 8. Assert that `clientMetadata` is identical to `updatedClientMetadata`.
+
+## Test 6: Metadata is not appended if identical to initial metadata (separated by non-identical metadata)
+
+1. Create a `MongoClient` instance with:
+
+    - `maxIdleTimeMS` set to `1ms`
+    - `driverInfo` set to the following:
+
+    | Field    | Value            |
+    | -------- | ---------------- |
+    | name     | library          |
+    | version  | 1.2              |
+    | platform | Library Platform |
+
+2. Send a `ping` command to the server and verify that the command succeeds.
+
+3. Wait 5ms for the connection to become idle.
+
+4. Append the following `DriverInfoOptions` to the `MongoClient` metadata:
+
+    | Field    | Value            |
+    | -------- | ---------------- |
+    | name     | framework        |
+    | version  | 1.2              |
+    | platform | Library Platform |
+
+5. Send a `ping` command to the server and verify that the command succeeds.
+
+6. Save intercepted `client` document as `clientMetadata`.
+
+7. Wait 5ms for the connection to become idle.
+
+8. Append the following `DriverInfoOptions` to the `MongoClient` metadata:
+
+    | Field    | Value            |
+    | -------- | ---------------- |
+    | name     | library          |
+    | version  | 1.2              |
+    | platform | Library Platform |
+
+9. Send a `ping` command to the server and verify that the command succeeds.
+
+10. Save intercepted `client` document as `updatedClientMetadata`.
+
+11. Assert that `clientMetadata` is identical to `updatedClientMetadata`.

From 9744e6977535c01ad60d9c5b86ef066629427051 Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Tue, 9 Sep 2025 13:53:45 -0600
Subject: [PATCH 08/15] ensure consistency with property assertions in tests

---
 source/mongodb-handshake/tests/README.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md
index 25b83b3d77..950146e784 100644
--- a/source/mongodb-handshake/tests/README.md
+++ b/source/mongodb-handshake/tests/README.md
@@ -142,7 +142,7 @@ Before each test case, perform the setup.
         - `client.driver.version`:
             - If test case's version is non-null: `1.2|<version>`
             - Otherwise, the field remains unchanged: `1.2`
-        - `client.driver.platform`:
+        - `client.platform`:
             - If test case's platform is non-null: `Library Platform|<platform>`
             - Otherwise, the field remains unchanged: `Library Platform`
 
@@ -259,13 +259,13 @@ Before each test case, perform the setup.
         info that is automatically added by the driver (ex: `metadata.name.split('|').slice(1).join('|')`).
 
         - If the test case's DriverInfo is identical to the driver info from setup step 2 (test case 1):
-            - Assert metadata.name is equal to `library`
-            - Assert metadata.version is equal to `1.2`
-            - Assert metadata.platform is equal to `LibraryPlatform`
+            - Assert `metadata.driver.name` is equal to `library`
+            - Assert `metadata.driver.version` is equal to `1.2`
+            - Assert `metadata.platform` is equal to `LibraryPlatform`
         - Otherwise:
-            - Assert metadata.name is equal to `library|<name>`
-            - Assert metadata.version is equal to `1.2|<version>`
-            - Assert metadata.platform is equal to `LibraryPlatform|<platform>`
+            - Assert `metadata.driver.name` is equal to `library|<name>`
+            - Assert `metadata.driver.version` is equal to `1.2|<version>`
+            - Assert `metadata.platform` is equal to `LibraryPlatform|<platform>`
 
     - All other subfields in the `client` document remain unchanged from `updatedClientMetadata`.
 

From fe170bb7578bb2912fcd1970411f873bc5068396 Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Tue, 9 Sep 2025 14:44:23 -0600
Subject: [PATCH 09/15] add new tests and update equality

---
 source/mongodb-handshake/handshake.md    |  5 +-
 source/mongodb-handshake/tests/README.md | 99 ++++++++++++++++++++++++
 2 files changed, 102 insertions(+), 2 deletions(-)

diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md
index cb8629a9fb..d6b7226f74 100644
--- a/source/mongodb-handshake/handshake.md
+++ b/source/mongodb-handshake/handshake.md
@@ -405,8 +405,9 @@ class DriverInfoOptions {
 }
 ```
 
-Two `DriverInfoOptions` objects are considered identical if all fields are strictly equal with case sensitive string
-comparison.
+Two `DriverInfoOptions` objects are considered equal if they would result in the same metadata in the client handshake.\
+In practice, this means if a field is the empty string (`""`), treat it as unset. Assert that each field is strictly
+equal with case sensitive string comparison.
 
 Note that how these options are provided to a driver during `MongoClient` initialization is left up to the implementer.
 
diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md
index 950146e784..01ed9d23bd 100644
--- a/source/mongodb-handshake/tests/README.md
+++ b/source/mongodb-handshake/tests/README.md
@@ -392,3 +392,102 @@ Before each test case, perform the setup.
 10. Save intercepted `client` document as `updatedClientMetadata`.
 
 11. Assert that `clientMetadata` is identical to `updatedClientMetadata`.
+
+## Test 7: Empty strings are considered unset when appending duplicate metadata
+
+Drivers should verify that after `MongoClient` initialization, metadata can be updated multiple times, not replaced, and
+is visible in the `hello` command of new connections.
+
+There are multiple test cases parameterized with `DriverInfoOptions` to be appended after a previous metadata update.
+Before each test case, perform the setup.
+
+#### Parameterized test cases
+
+##### Initial metadata
+
+| Case | Name    | Version | Platform         |
+| ---- | ------- | ------- | ---------------- |
+| 1    | null    | 1.2     | Library Platform |
+| 2    | library | null    | Library Platform |
+| 3    | library | 1.2     | null             |
+
+##### Appended Metadata
+
+| Case | Name    | Version | Platform         |
+| ---- | ------- | ------- | ---------------- |
+| 1    | ""      | 1.2     | Library Platform |
+| 2    | library | ""      | Library Platform |
+| 3    | library | 1.2     | ""               |
+
+### Setup
+
+1. Create a `MongoClient` instance with:
+
+    - `maxIdleTimeMS` set to `1ms`
+
+2. Append the `DriverInfoOptions` from the selected test case from the initial metadata section.
+
+3. Send a `ping` command to the server and verify that the command succeeds.
+
+4. Save intercepted `client` document as `initialClientMetadata`.
+
+5. Wait 5ms for the connection to become idle.
+
+#### Running a test case
+
+1. Append the `DriverInfoOptions` from the selected test case from the appended metadata section.
+
+2. Send a `ping` command to the server and verify the command succeeds.
+
+3. Store the response as `updatedClientMetadata`.
+
+4. Assert that `initialClientMetadata` is identical to `updatedClientMetadata`.
+
+## Test 8: Empty strings are considered unset when appending metadata identical to initial metadata
+
+Drivers should verify that after `MongoClient` initialization, metadata can be updated multiple times, not replaced, and
+is visible in the `hello` command of new connections.
+
+There are multiple test cases parameterized with `DriverInfoOptions` to be appended after a previous metadata update.
+Before each test case, perform the setup.
+
+#### Parameterized test cases
+
+##### Initial metadata
+
+| Case | Name    | Version | Platform         |
+| ---- | ------- | ------- | ---------------- |
+| 1    | null    | 1.2     | Library Platform |
+| 2    | library | null    | Library Platform |
+| 3    | library | 1.2     | null             |
+
+##### Appended Metadata
+
+| Case | Name    | Version | Platform         |
+| ---- | ------- | ------- | ---------------- |
+| 1    | ""      | 1.2     | Library Platform |
+| 2    | library | ""      | Library Platform |
+| 3    | library | 1.2     | ""               |
+
+### Setup
+
+1. Create a `MongoClient` instance with:
+
+    - `maxIdleTimeMS` set to `1ms`
+    - `driverInfo` set to the `DriverInfoOptions` from the selected test case from the initial metadata section.
+
+2. Send a `ping` command to the server and verify that the command succeeds.
+
+3. Save intercepted `client` document as `initialClientMetadata`.
+
+4. Wait 5ms for the connection to become idle.
+
+#### Running a test case
+
+1. Append the `DriverInfoOptions` from the selected test case from the appended metadata section.
+
+2. Send a `ping` command to the server and verify the command succeeds.
+
+3. Store the response as `updatedClientMetadata`.
+
+4. Assert that `initialClientMetadata` is identical to `updatedClientMetadata`.

From 4fb3d1e3efeee7b7e90ff10a7f5e348fd4c963fa Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Tue, 9 Sep 2025 15:16:08 -0600
Subject: [PATCH 10/15] fix numbering

---
 source/mongodb-handshake/tests/README.md | 24 ++++++++++--------------
 1 file changed, 10 insertions(+), 14 deletions(-)

diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md
index 01ed9d23bd..c3c5ce8150 100644
--- a/source/mongodb-handshake/tests/README.md
+++ b/source/mongodb-handshake/tests/README.md
@@ -419,7 +419,7 @@ Before each test case, perform the setup.
 | 2    | library | ""      | Library Platform |
 | 3    | library | 1.2     | ""               |
 
-### Setup
+#### Running a test case
 
 1. Create a `MongoClient` instance with:
 
@@ -433,15 +433,13 @@ Before each test case, perform the setup.
 
 5. Wait 5ms for the connection to become idle.
 
-#### Running a test case
-
-1. Append the `DriverInfoOptions` from the selected test case from the appended metadata section.
+6. Append the `DriverInfoOptions` from the selected test case from the appended metadata section.
 
-2. Send a `ping` command to the server and verify the command succeeds.
+7. Send a `ping` command to the server and verify the command succeeds.
 
-3. Store the response as `updatedClientMetadata`.
+8. Store the response as `updatedClientMetadata`.
 
-4. Assert that `initialClientMetadata` is identical to `updatedClientMetadata`.
+9. Assert that `initialClientMetadata` is identical to `updatedClientMetadata`.
 
 ## Test 8: Empty strings are considered unset when appending metadata identical to initial metadata
 
@@ -469,7 +467,7 @@ Before each test case, perform the setup.
 | 2    | library | ""      | Library Platform |
 | 3    | library | 1.2     | ""               |
 
-### Setup
+#### Running a test case
 
 1. Create a `MongoClient` instance with:
 
@@ -482,12 +480,10 @@ Before each test case, perform the setup.
 
 4. Wait 5ms for the connection to become idle.
 
-#### Running a test case
-
-1. Append the `DriverInfoOptions` from the selected test case from the appended metadata section.
+5. Append the `DriverInfoOptions` from the selected test case from the appended metadata section.
 
-2. Send a `ping` command to the server and verify the command succeeds.
+6. Send a `ping` command to the server and verify the command succeeds.
 
-3. Store the response as `updatedClientMetadata`.
+7. Store the response as `updatedClientMetadata`.
 
-4. Assert that `initialClientMetadata` is identical to `updatedClientMetadata`.
+8. Assert that `initialClientMetadata` is identical to `updatedClientMetadata`.

From 2e622ba440b3a715abdf3ffbbf73f910a0484fc8 Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Wed, 10 Sep 2025 07:15:41 -0600
Subject: [PATCH 11/15] preston's, daria's and Anna's comments

---
 source/mongodb-handshake/handshake.md    |  4 +--
 source/mongodb-handshake/tests/README.md | 42 ++++++++++++------------
 2 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md
index d6b7226f74..24ad524405 100644
--- a/source/mongodb-handshake/handshake.md
+++ b/source/mongodb-handshake/handshake.md
@@ -405,7 +405,7 @@ class DriverInfoOptions {
 }
 ```
 
-Two `DriverInfoOptions` objects are considered equal if they would result in the same metadata in the client handshake.\
+Two `DriverInfoOptions` objects are considered equal if they would result in the same metadata in the client handshake.
 In practice, this means if a field is the empty string (`""`), treat it as unset. Assert that each field is strictly
 equal with case sensitive string comparison.
 
@@ -448,7 +448,7 @@ be appended to their respective fields, and be delimited by a `|` character. For
 
 Some client libraries provide APIs that accept a pre-initialized MongoClient as an argument. In these circumstances, it
 is possible for multiple library objects to be associated with the same MongoClient, which could result in the same
-metadata being appended multiple times. Drivers MUST ensure that a `DriverInfo` objects provided to a MongoClient or
+metadata being appended multiple times. Drivers MUST ensure that all `DriverInfo` objects provided to a MongoClient or
 appended to a MongoClient are distinct (see [Supporting Wrapping Libraries](#supporting-wrapping-libraries)).
 
 **NOTE:** All strings provided as part of the driver info MUST NOT contain the delimiter used for metadata concatention.
diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md
index c3c5ce8150..6dbfb26f6f 100644
--- a/source/mongodb-handshake/tests/README.md
+++ b/source/mongodb-handshake/tests/README.md
@@ -148,7 +148,7 @@ Before each test case, perform the setup.
 
     - All other subfields in the `client` document remain unchanged from `initialClientMetadata`.
 
-## Test 2: Multiple Successive Metadata Updates
+### Test 2: Multiple Successive Metadata Updates
 
 Drivers should verify that after `MongoClient` initialization, metadata can be updated multiple times, not replaced, and
 is visible in the `hello` command of new connections.
@@ -156,7 +156,7 @@ is visible in the `hello` command of new connections.
 There are multiple test cases parameterized with `DriverInfoOptions` to be appended after a previous metadata update.
 Before each test case, perform the setup.
 
-### Setup
+#### Setup
 
 1. Create a `MongoClient` instance with:
 
@@ -176,7 +176,7 @@ Before each test case, perform the setup.
 
 5. Wait 5ms for the connection to become idle.
 
-#### Parameterized test cases
+##### Parameterized test cases
 
 | Case | Name      | Version | Platform           |
 | ---- | --------- | ------- | ------------------ |
@@ -185,7 +185,7 @@ Before each test case, perform the setup.
 | 3    | framework | null    | Framework Platform |
 | 4    | framework | null    | null               |
 
-#### Running a test case
+##### Running a test case
 
 1. Append the `DriverInfoOptions` from the selected test case to the `MongoClient` metadata.
 
@@ -208,12 +208,12 @@ Before each test case, perform the setup.
 
     - All other subfields in the `client` document remain unchanged from `updatedClientMetadata`.
 
-## Test 3: Multiple Successive Metadata Updates with Duplicate Data
+### Test 3: Multiple Successive Metadata Updates with Duplicate Data
 
 There are multiple test cases parameterized with `DriverInfoOptions` to be appended after a previous metadata update.
 Before each test case, perform the setup.
 
-### Setup
+#### Setup
 
 1. Create a `MongoClient` instance with:
 
@@ -233,7 +233,7 @@ Before each test case, perform the setup.
 
 5. Wait 5ms for the connection to become idle.
 
-#### Parameterized test cases
+##### Parameterized test cases
 
 | Case | Name      | Version | Platform           |
 | ---- | --------- | ------- | ------------------ |
@@ -246,7 +246,7 @@ Before each test case, perform the setup.
 | 7    | library   | 2.0     | Framework Platform |
 | 8    | framework | 2.0     | Framework Platform |
 
-#### Running a test case
+##### Running a test case
 
 1. Append the `DriverInfoOptions` from the selected test case to the `MongoClient` metadata.
 
@@ -269,7 +269,7 @@ Before each test case, perform the setup.
 
     - All other subfields in the `client` document remain unchanged from `updatedClientMetadata`.
 
-## Test 4: Multiple Metadata Updates with Duplicate Data
+### Test 4: Multiple Metadata Updates with Duplicate Data
 
 1. Create a `MongoClient` instance with:
 
@@ -315,7 +315,7 @@ Before each test case, perform the setup.
 
 12. Assert that `clientMetadata` is identical to `updatedClientMetadata`.
 
-## Test 5: Metadata is not appended if identical to initial metadata
+### Test 5: Metadata is not appended if identical to initial metadata
 
 1. Create a `MongoClient` instance with:
 
@@ -348,7 +348,7 @@ Before each test case, perform the setup.
 
 8. Assert that `clientMetadata` is identical to `updatedClientMetadata`.
 
-## Test 6: Metadata is not appended if identical to initial metadata (separated by non-identical metadata)
+### Test 6: Metadata is not appended if identical to initial metadata (separated by non-identical metadata)
 
 1. Create a `MongoClient` instance with:
 
@@ -393,7 +393,7 @@ Before each test case, perform the setup.
 
 11. Assert that `clientMetadata` is identical to `updatedClientMetadata`.
 
-## Test 7: Empty strings are considered unset when appending duplicate metadata
+### Test 7: Empty strings are considered unset when appending duplicate metadata
 
 Drivers should verify that after `MongoClient` initialization, metadata can be updated multiple times, not replaced, and
 is visible in the `hello` command of new connections.
@@ -401,9 +401,9 @@ is visible in the `hello` command of new connections.
 There are multiple test cases parameterized with `DriverInfoOptions` to be appended after a previous metadata update.
 Before each test case, perform the setup.
 
-#### Parameterized test cases
+##### Parameterized test cases
 
-##### Initial metadata
+###### Initial metadata
 
 | Case | Name    | Version | Platform         |
 | ---- | ------- | ------- | ---------------- |
@@ -411,7 +411,7 @@ Before each test case, perform the setup.
 | 2    | library | null    | Library Platform |
 | 3    | library | 1.2     | null             |
 
-##### Appended Metadata
+###### Appended Metadata
 
 | Case | Name    | Version | Platform         |
 | ---- | ------- | ------- | ---------------- |
@@ -419,7 +419,7 @@ Before each test case, perform the setup.
 | 2    | library | ""      | Library Platform |
 | 3    | library | 1.2     | ""               |
 
-#### Running a test case
+##### Running a test case
 
 1. Create a `MongoClient` instance with:
 
@@ -441,7 +441,7 @@ Before each test case, perform the setup.
 
 9. Assert that `initialClientMetadata` is identical to `updatedClientMetadata`.
 
-## Test 8: Empty strings are considered unset when appending metadata identical to initial metadata
+### Test 8: Empty strings are considered unset when appending metadata identical to initial metadata
 
 Drivers should verify that after `MongoClient` initialization, metadata can be updated multiple times, not replaced, and
 is visible in the `hello` command of new connections.
@@ -449,9 +449,9 @@ is visible in the `hello` command of new connections.
 There are multiple test cases parameterized with `DriverInfoOptions` to be appended after a previous metadata update.
 Before each test case, perform the setup.
 
-#### Parameterized test cases
+##### Parameterized test cases
 
-##### Initial metadata
+###### Initial metadata
 
 | Case | Name    | Version | Platform         |
 | ---- | ------- | ------- | ---------------- |
@@ -459,7 +459,7 @@ Before each test case, perform the setup.
 | 2    | library | null    | Library Platform |
 | 3    | library | 1.2     | null             |
 
-##### Appended Metadata
+###### Appended Metadata
 
 | Case | Name    | Version | Platform         |
 | ---- | ------- | ------- | ---------------- |
@@ -467,7 +467,7 @@ Before each test case, perform the setup.
 | 2    | library | ""      | Library Platform |
 | 3    | library | 1.2     | ""               |
 
-#### Running a test case
+##### Running a test case
 
 1. Create a `MongoClient` instance with:
 

From 4b9968f54e5882defea9b2245861c5759c3821b0 Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Wed, 10 Sep 2025 13:49:49 -0600
Subject: [PATCH 12/15] comments

---
 source/mongodb-handshake/handshake.md    | 5 +++--
 source/mongodb-handshake/tests/README.md | 1 -
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md
index 24ad524405..ff4f363106 100644
--- a/source/mongodb-handshake/handshake.md
+++ b/source/mongodb-handshake/handshake.md
@@ -448,8 +448,9 @@ be appended to their respective fields, and be delimited by a `|` character. For
 
 Some client libraries provide APIs that accept a pre-initialized MongoClient as an argument. In these circumstances, it
 is possible for multiple library objects to be associated with the same MongoClient, which could result in the same
-metadata being appended multiple times. Drivers MUST ensure that all `DriverInfo` objects provided to a MongoClient or
-appended to a MongoClient are distinct (see [Supporting Wrapping Libraries](#supporting-wrapping-libraries)).
+metadata being appended multiple times. Drivers MUST ensure that all `DriverInfoOptions` objects provided to a
+MongoClient or appended to a MongoClient are distinct (see
+[Supporting Wrapping Libraries](#supporting-wrapping-libraries)).
 
 **NOTE:** All strings provided as part of the driver info MUST NOT contain the delimiter used for metadata concatention.
 Drivers MUST throw an error if any of these strings contains that character.
diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md
index 6dbfb26f6f..d88a49fa92 100644
--- a/source/mongodb-handshake/tests/README.md
+++ b/source/mongodb-handshake/tests/README.md
@@ -244,7 +244,6 @@ Before each test case, perform the setup.
 | 5    | framework | 2.0     | Library Platform   |
 | 6    | framework | 1.2     | Framework Platform |
 | 7    | library   | 2.0     | Framework Platform |
-| 8    | framework | 2.0     | Framework Platform |
 
 ##### Running a test case
 

From 5d47d3b3365c339dfb788b1c3d58887fd7a2cb7a Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Wed, 10 Sep 2025 13:52:26 -0600
Subject: [PATCH 13/15] comments

---
 source/mongodb-handshake/handshake.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md
index ff4f363106..fbafce7a13 100644
--- a/source/mongodb-handshake/handshake.md
+++ b/source/mongodb-handshake/handshake.md
@@ -448,9 +448,9 @@ be appended to their respective fields, and be delimited by a `|` character. For
 
 Some client libraries provide APIs that accept a pre-initialized MongoClient as an argument. In these circumstances, it
 is possible for multiple library objects to be associated with the same MongoClient, which could result in the same
-metadata being appended multiple times. Drivers MUST ensure that all `DriverInfoOptions` objects provided to a
+metadata being appended multiple times. Drivers MUST ensure that any duplicate `DriverInfoOptions` objects provided to a
 MongoClient or appended to a MongoClient are distinct (see
-[Supporting Wrapping Libraries](#supporting-wrapping-libraries)).
+[Supporting Wrapping Libraries](#supporting-wrapping-libraries)) are a no-op.
 
 **NOTE:** All strings provided as part of the driver info MUST NOT contain the delimiter used for metadata concatention.
 Drivers MUST throw an error if any of these strings contains that character.

From f76b2dac3b0441c5b53815ee1c5e29de0ec98d17 Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Wed, 10 Sep 2025 14:09:30 -0600
Subject: [PATCH 14/15] fix phrasing

---
 source/mongodb-handshake/handshake.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md
index fbafce7a13..bfddef82e9 100644
--- a/source/mongodb-handshake/handshake.md
+++ b/source/mongodb-handshake/handshake.md
@@ -449,8 +449,8 @@ be appended to their respective fields, and be delimited by a `|` character. For
 Some client libraries provide APIs that accept a pre-initialized MongoClient as an argument. In these circumstances, it
 is possible for multiple library objects to be associated with the same MongoClient, which could result in the same
 metadata being appended multiple times. Drivers MUST ensure that any duplicate `DriverInfoOptions` objects provided to a
-MongoClient or appended to a MongoClient are distinct (see
-[Supporting Wrapping Libraries](#supporting-wrapping-libraries)) are a no-op.
+MongoClient or appended to a MongoClient do not result in additional metadata being appended (i.e., a no-op). See
+[Supporting Wrapping Libraries](#supporting-wrapping-libraries).
 
 **NOTE:** All strings provided as part of the driver info MUST NOT contain the delimiter used for metadata concatention.
 Drivers MUST throw an error if any of these strings contains that character.

From a332db9abf7bdee986f02f947e28c1acc666b88c Mon Sep 17 00:00:00 2001
From: bailey <bailey.pearson@mongodb.com>
Date: Wed, 10 Sep 2025 14:59:52 -0600
Subject: [PATCH 15/15] remove no-op language

---
 source/mongodb-handshake/handshake.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md
index bfddef82e9..24c6eea50d 100644
--- a/source/mongodb-handshake/handshake.md
+++ b/source/mongodb-handshake/handshake.md
@@ -449,7 +449,7 @@ be appended to their respective fields, and be delimited by a `|` character. For
 Some client libraries provide APIs that accept a pre-initialized MongoClient as an argument. In these circumstances, it
 is possible for multiple library objects to be associated with the same MongoClient, which could result in the same
 metadata being appended multiple times. Drivers MUST ensure that any duplicate `DriverInfoOptions` objects provided to a
-MongoClient or appended to a MongoClient do not result in additional metadata being appended (i.e., a no-op). See
+MongoClient or appended to a MongoClient do not result in additional metadata being appended. See
 [Supporting Wrapping Libraries](#supporting-wrapping-libraries).
 
 **NOTE:** All strings provided as part of the driver info MUST NOT contain the delimiter used for metadata concatention.