From d66cc5c9b26d2c36bf1bba12729445dfe95d319d Mon Sep 17 00:00:00 2001
From: Ross Lawley <ross.lawley@gmail.com>
Date: Mon, 6 Oct 2025 16:32:59 +0100
Subject: [PATCH 1/2] Annotated all internal packages

JAVA-5975
---
 .../internal/async/function/package-info.java        |  6 ++++++
 .../com/mongodb/internal/async/package-info.java     |  3 +++
 .../internal/authentication/package-info.java        |  4 ++++
 .../com/mongodb/internal/binding/package-info.java   |  4 +++-
 .../main/com/mongodb/internal/bulk/package-info.java |  4 +++-
 .../main/com/mongodb/internal/capi/package-info.java |  5 ++++-
 .../internal/client/model/bulk/package-info.java     |  5 ++++-
 .../client/model/changestream/package-info.java      |  4 +++-
 .../mongodb/internal/client/model/package-info.java  |  4 +++-
 .../com/mongodb/internal/client/package-info.java    |  4 +++-
 .../mongodb/internal/client/vault/package-info.java  |  4 +++-
 .../internal/connection/netty/package-info.java      |  5 ++++-
 .../mongodb/internal/connection/package-info.java    |  5 +++--
 .../connection/tlschannel/async/package-info.java    |  6 ++++--
 .../internal/connection/tlschannel/package-info.java | 12 ++++--------
 .../internal/diagnostics/logging/package-info.java   |  5 +++--
 .../main/com/mongodb/internal/dns/package-info.java  |  5 +++--
 .../com/mongodb/internal/event/package-info.java     |  5 +++--
 .../com/mongodb/internal/function/package-info.java  |  4 +++-
 .../com/mongodb/internal/inject/package-info.java    |  5 +++--
 .../com/mongodb/internal/logging/package-info.java   |  5 +++--
 .../com/mongodb/internal/operation/package-info.java |  5 +++--
 .../internal/operation/retry/package-info.java       |  5 +++--
 .../src/main/com/mongodb/internal/package-info.java  |  3 +++
 .../com/mongodb/internal/selector/package-info.java  |  5 +++--
 .../com/mongodb/internal/session/package-info.java   |  5 +++--
 .../com/mongodb/internal/thread/package-info.java    |  5 +++--
 .../main/com/mongodb/internal/time/package-info.java |  4 +++-
 .../com/mongodb/internal/validator/package-info.java |  5 +++--
 .../client/internal/crypt/package-info.java          |  6 +++---
 .../client/internal/gridfs/package-info.java         |  6 +++---
 .../client/internal/package-info.java                |  7 ++++---
 .../client/internal/vault/package-info.java          |  6 +++---
 .../com/mongodb/client/internal/package-info.java    |  5 +++++
 34 files changed, 114 insertions(+), 57 deletions(-)

diff --git a/driver-core/src/main/com/mongodb/internal/async/function/package-info.java b/driver-core/src/main/com/mongodb/internal/async/function/package-info.java
index e85d91432a2..2a89dc73a54 100644
--- a/driver-core/src/main/com/mongodb/internal/async/function/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/async/function/package-info.java
@@ -14,7 +14,13 @@
  * limitations under the License.
  */
 
+/**
+ * This package contains internal functionality that may change at any time.
+ */
+
+@Internal
 @NonNullApi
 package com.mongodb.internal.async.function;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/async/package-info.java b/driver-core/src/main/com/mongodb/internal/async/package-info.java
index 39b952eead1..c6c62967258 100644
--- a/driver-core/src/main/com/mongodb/internal/async/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/async/package-info.java
@@ -15,9 +15,12 @@
  */
 
 /**
+ * This package contains internal functionality that may change at any time.
  */
 
+@Internal
 @NonNullApi
 package com.mongodb.internal.async;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/authentication/package-info.java b/driver-core/src/main/com/mongodb/internal/authentication/package-info.java
index bbeb09628af..5a0915e39a3 100644
--- a/driver-core/src/main/com/mongodb/internal/authentication/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/authentication/package-info.java
@@ -15,9 +15,13 @@
  */
 
 /**
+ * This package contains internal functionality that may change at any time.
  */
 
+
+@Internal
 @NonNullApi
 package com.mongodb.internal.authentication;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/binding/package-info.java b/driver-core/src/main/com/mongodb/internal/binding/package-info.java
index 57d1f7430b7..d514628e1b4 100644
--- a/driver-core/src/main/com/mongodb/internal/binding/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/binding/package-info.java
@@ -15,10 +15,12 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
 
+@Internal
 @NonNullApi
 package com.mongodb.internal.binding;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/bulk/package-info.java b/driver-core/src/main/com/mongodb/internal/bulk/package-info.java
index 936893bcfe5..40daa3eec72 100644
--- a/driver-core/src/main/com/mongodb/internal/bulk/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/bulk/package-info.java
@@ -15,10 +15,12 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
 
+@Internal
 @NonNullApi
 package com.mongodb.internal.bulk;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/capi/package-info.java b/driver-core/src/main/com/mongodb/internal/capi/package-info.java
index e0feb7fb9f0..d903b56c422 100644
--- a/driver-core/src/main/com/mongodb/internal/capi/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/capi/package-info.java
@@ -15,10 +15,13 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
 
+
+@Internal
 @NonNullApi
 package com.mongodb.internal.capi;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/client/model/bulk/package-info.java b/driver-core/src/main/com/mongodb/internal/client/model/bulk/package-info.java
index 2d66f44646b..c344a50368d 100644
--- a/driver-core/src/main/com/mongodb/internal/client/model/bulk/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/client/model/bulk/package-info.java
@@ -15,9 +15,12 @@
  */
 
 /**
- * Internal program elements related to {@link com.mongodb.client.model.bulk}.
+ * This package contains internal functionality that may change at any time.
  */
+
+@Internal
 @NonNullApi
 package com.mongodb.internal.client.model.bulk;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/client/model/changestream/package-info.java b/driver-core/src/main/com/mongodb/internal/client/model/changestream/package-info.java
index edbdd14c856..35e0c4b5176 100644
--- a/driver-core/src/main/com/mongodb/internal/client/model/changestream/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/client/model/changestream/package-info.java
@@ -15,10 +15,12 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
 
+@Internal
 @NonNullApi
 package com.mongodb.internal.client.model.changestream;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/client/model/package-info.java b/driver-core/src/main/com/mongodb/internal/client/model/package-info.java
index 574e6d0bcc6..f37e6c84515 100644
--- a/driver-core/src/main/com/mongodb/internal/client/model/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/client/model/package-info.java
@@ -15,10 +15,12 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
 
+@Internal
 @NonNullApi
 package com.mongodb.internal.client.model;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/client/package-info.java b/driver-core/src/main/com/mongodb/internal/client/package-info.java
index 03c3a2bfd9b..347b327f571 100644
--- a/driver-core/src/main/com/mongodb/internal/client/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/client/package-info.java
@@ -15,10 +15,12 @@
  */
 
 /**
- * This package contains classes for internal client functionality.
+ * This package contains internal functionality that may change at any time.
  */
 
+@Internal
 @NonNullApi
 package com.mongodb.internal.client;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/client/vault/package-info.java b/driver-core/src/main/com/mongodb/internal/client/vault/package-info.java
index 51c351d1e1f..83322719b00 100644
--- a/driver-core/src/main/com/mongodb/internal/client/vault/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/client/vault/package-info.java
@@ -15,10 +15,12 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
 
+@Internal
 @NonNullApi
 package com.mongodb.internal.client.vault;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/connection/netty/package-info.java b/driver-core/src/main/com/mongodb/internal/connection/netty/package-info.java
index f19b029d031..f8a61623538 100644
--- a/driver-core/src/main/com/mongodb/internal/connection/netty/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/connection/netty/package-info.java
@@ -15,9 +15,12 @@
  */
 
 /**
- * Contains <a href="https://netty.io/">Netty</a>-specific program elements.
+ * This package contains internal functionality that may change at any time.
  */
+
+@Internal
 @NonNullApi
 package com.mongodb.internal.connection.netty;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/connection/package-info.java b/driver-core/src/main/com/mongodb/internal/connection/package-info.java
index c3f2f35acdd..f1b0349c963 100644
--- a/driver-core/src/main/com/mongodb/internal/connection/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/connection/package-info.java
@@ -15,10 +15,11 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
-
+@Internal
 @NonNullApi
 package com.mongodb.internal.connection;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/connection/tlschannel/async/package-info.java b/driver-core/src/main/com/mongodb/internal/connection/tlschannel/async/package-info.java
index 637580fb72f..14335d5c0d5 100644
--- a/driver-core/src/main/com/mongodb/internal/connection/tlschannel/async/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/connection/tlschannel/async/package-info.java
@@ -18,7 +18,9 @@
  */
 
 /**
- * This package enables the usage of TLS Channel as an {@link
- * java.nio.channels.AsynchronousByteChannel}.
+ * This package contains internal functionality that may change at any time.
  */
+@Internal
 package com.mongodb.internal.connection.tlschannel.async;
+
+import com.mongodb.annotations.Internal;
diff --git a/driver-core/src/main/com/mongodb/internal/connection/tlschannel/package-info.java b/driver-core/src/main/com/mongodb/internal/connection/tlschannel/package-info.java
index 230fb17d6f8..e6332466491 100644
--- a/driver-core/src/main/com/mongodb/internal/connection/tlschannel/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/connection/tlschannel/package-info.java
@@ -18,13 +18,9 @@
  */
 
 /**
- * TLS Channel is a library that implements a ByteChannel interface to a TLS (Transport Layer
- * Security) connection. The library delegates all cryptographic operations to the standard Java TLS
- * implementation: SSLEngine; effectively hiding it behind an easy-to-use streaming API, that allows
- * to securitize JVM applications with minimal added complexity.
- *
- * <p>In other words, a simple library that allows the programmer to have TLS using the same
- * standard socket API used for plaintext, just like OpenSSL does for C, only for Java, filling a
- * specially painful missing feature of the standard Java library.
+ * This package contains internal functionality that may change at any time.
  */
+@Internal
 package com.mongodb.internal.connection.tlschannel;
+
+import com.mongodb.annotations.Internal;
diff --git a/driver-core/src/main/com/mongodb/internal/diagnostics/logging/package-info.java b/driver-core/src/main/com/mongodb/internal/diagnostics/logging/package-info.java
index 2a1b56a59ed..44488d7ecaa 100644
--- a/driver-core/src/main/com/mongodb/internal/diagnostics/logging/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/diagnostics/logging/package-info.java
@@ -15,10 +15,11 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
-
+@Internal
 @NonNullApi
 package com.mongodb.internal.diagnostics.logging;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/dns/package-info.java b/driver-core/src/main/com/mongodb/internal/dns/package-info.java
index 6c516f9237e..e02c7f1ebe8 100644
--- a/driver-core/src/main/com/mongodb/internal/dns/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/dns/package-info.java
@@ -15,10 +15,11 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
-
+@Internal
 @NonNullApi
 package com.mongodb.internal.dns;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/event/package-info.java b/driver-core/src/main/com/mongodb/internal/event/package-info.java
index a595943297c..f36c52a8298 100644
--- a/driver-core/src/main/com/mongodb/internal/event/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/event/package-info.java
@@ -15,10 +15,11 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
-
+@Internal
 @NonNullApi
 package com.mongodb.internal.event;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/function/package-info.java b/driver-core/src/main/com/mongodb/internal/function/package-info.java
index baea9b145ec..50db2793b8a 100644
--- a/driver-core/src/main/com/mongodb/internal/function/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/function/package-info.java
@@ -15,9 +15,11 @@
  */
 
 /**
+ * This package contains internal functionality that may change at any time.
  */
-
+@Internal
 @NonNullApi
 package com.mongodb.internal.function;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/inject/package-info.java b/driver-core/src/main/com/mongodb/internal/inject/package-info.java
index 6e7581a8c45..34ad231d106 100644
--- a/driver-core/src/main/com/mongodb/internal/inject/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/inject/package-info.java
@@ -15,10 +15,11 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
-
+@Internal
 @NonNullApi
 package com.mongodb.internal.inject;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/logging/package-info.java b/driver-core/src/main/com/mongodb/internal/logging/package-info.java
index f244a5b3529..74810176f88 100644
--- a/driver-core/src/main/com/mongodb/internal/logging/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/logging/package-info.java
@@ -15,10 +15,11 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
-
+@Internal
 @NonNullApi
 package com.mongodb.internal.logging;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/operation/package-info.java b/driver-core/src/main/com/mongodb/internal/operation/package-info.java
index ac3047a2295..ffd207916d1 100644
--- a/driver-core/src/main/com/mongodb/internal/operation/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/operation/package-info.java
@@ -15,10 +15,11 @@
  */
 
 /**
- * The core of the MongoDB driver works via operations, using the command pattern. The main Operations supported by MongoDB are in this
- * package, as are helpers and infrastructure required for operation functionality.
+ * This package contains internal functionality that may change at any time.
  */
+@Internal
 @NonNullApi
 package com.mongodb.internal.operation;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/operation/retry/package-info.java b/driver-core/src/main/com/mongodb/internal/operation/retry/package-info.java
index 7e398f7de92..29c27a47914 100644
--- a/driver-core/src/main/com/mongodb/internal/operation/retry/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/operation/retry/package-info.java
@@ -15,10 +15,11 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
-
+@Internal
 @NonNullApi
 package com.mongodb.internal.operation.retry;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/package-info.java b/driver-core/src/main/com/mongodb/internal/package-info.java
index e7825fe1292..52023d78b75 100644
--- a/driver-core/src/main/com/mongodb/internal/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/package-info.java
@@ -15,9 +15,12 @@
  */
 
 /**
+ * This package contains internal functionality that may change at any time.
  */
 
+@Internal
 @NonNullApi
 package com.mongodb.internal;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/selector/package-info.java b/driver-core/src/main/com/mongodb/internal/selector/package-info.java
index 6514d4daf10..ab05e07c087 100644
--- a/driver-core/src/main/com/mongodb/internal/selector/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/selector/package-info.java
@@ -15,10 +15,11 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
-
+@Internal
 @NonNullApi
 package com.mongodb.internal.selector;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/session/package-info.java b/driver-core/src/main/com/mongodb/internal/session/package-info.java
index a681216a67c..faeb3aeaac4 100644
--- a/driver-core/src/main/com/mongodb/internal/session/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/session/package-info.java
@@ -15,10 +15,11 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
-
+@Internal
 @NonNullApi
 package com.mongodb.internal.session;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/thread/package-info.java b/driver-core/src/main/com/mongodb/internal/thread/package-info.java
index e005dc65132..e5a0a9f7237 100644
--- a/driver-core/src/main/com/mongodb/internal/thread/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/thread/package-info.java
@@ -15,10 +15,11 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
-
+@Internal
 @NonNullApi
 package com.mongodb.internal.thread;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/time/package-info.java b/driver-core/src/main/com/mongodb/internal/time/package-info.java
index 3b3ee457517..deb84634964 100644
--- a/driver-core/src/main/com/mongodb/internal/time/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/time/package-info.java
@@ -15,9 +15,11 @@
  */
 
 /**
- * This package contains program elements for working with time.
+ * This package contains internal functionality that may change at any time.
  */
+@Internal
 @NonNullApi
 package com.mongodb.internal.time;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-core/src/main/com/mongodb/internal/validator/package-info.java b/driver-core/src/main/com/mongodb/internal/validator/package-info.java
index cba0de48497..cec46638fb5 100644
--- a/driver-core/src/main/com/mongodb/internal/validator/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/validator/package-info.java
@@ -15,10 +15,11 @@
  */
 
 /**
- * This package contains classes that manage binding to MongoDB servers for various operations.
+ * This package contains internal functionality that may change at any time.
  */
-
+@Internal
 @NonNullApi
 package com.mongodb.internal.validator;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/crypt/package-info.java b/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/crypt/package-info.java
index 759ba586997..3311b31a9d8 100644
--- a/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/crypt/package-info.java
+++ b/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/crypt/package-info.java
@@ -15,11 +15,11 @@
  */
 
 /**
- * Utility classes for internal library use only.
- *
- * <p>This should not be considered a part of the public API.</p>
+ * This package contains internal functionality that may change at any time.
  */
+@Internal
 @NonNullApi
 package com.mongodb.reactivestreams.client.internal.crypt;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/gridfs/package-info.java b/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/gridfs/package-info.java
index ce1f07cc2ba..d2582b398da 100644
--- a/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/gridfs/package-info.java
+++ b/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/gridfs/package-info.java
@@ -15,11 +15,11 @@
  */
 
 /**
- * Utility classes for internal library use only.
- *
- * <p>This should not be considered a part of the public API.</p>
+ * This package contains internal functionality that may change at any time.
  */
+@Internal
 @NonNullApi
 package com.mongodb.reactivestreams.client.internal.gridfs;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/package-info.java b/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/package-info.java
index 3b650b4a715..b683433d231 100644
--- a/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/package-info.java
+++ b/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/package-info.java
@@ -15,11 +15,12 @@
  */
 
 /**
- * Utility classes for internal library use only.
- *
- * <p>This should not be considered a part of the public API.</p>
+ * This package contains internal functionality that may change at any time.
  */
+
+@Internal
 @NonNullApi
 package com.mongodb.reactivestreams.client.internal;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/vault/package-info.java b/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/vault/package-info.java
index 59b16b7cc4f..c4f3d32544a 100644
--- a/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/vault/package-info.java
+++ b/driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/vault/package-info.java
@@ -15,11 +15,11 @@
  */
 
 /**
- * Utility classes for internal library use only.
- *
- * <p>This should not be considered a part of the public API.</p>
+ * This package contains internal functionality that may change at any time.
  */
+@Internal
 @NonNullApi
 package com.mongodb.reactivestreams.client.internal.vault;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;
diff --git a/driver-sync/src/main/com/mongodb/client/internal/package-info.java b/driver-sync/src/main/com/mongodb/client/internal/package-info.java
index 4ad4a9813dd..4d3affbab2e 100644
--- a/driver-sync/src/main/com/mongodb/client/internal/package-info.java
+++ b/driver-sync/src/main/com/mongodb/client/internal/package-info.java
@@ -14,7 +14,12 @@
  * limitations under the License.
  */
 
+/**
+ * This package contains internal functionality that may change at any time.
+ */
+@Internal
 @NonNullApi
 package com.mongodb.client.internal;
 
+import com.mongodb.annotations.Internal;
 import com.mongodb.lang.NonNullApi;

From 5beb79990d69f348a3b4eda2d0356aefb709578b Mon Sep 17 00:00:00 2001
From: Ross Lawley <ross.lawley@gmail.com>
Date: Thu, 9 Oct 2025 13:15:40 +0100
Subject: [PATCH 2/2] Put back tlschannel javadoc

---
 .../connection/tlschannel/async/package-info.java     |  5 ++++-
 .../internal/connection/tlschannel/package-info.java  | 11 ++++++++++-
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/driver-core/src/main/com/mongodb/internal/connection/tlschannel/async/package-info.java b/driver-core/src/main/com/mongodb/internal/connection/tlschannel/async/package-info.java
index 14335d5c0d5..d04052254d4 100644
--- a/driver-core/src/main/com/mongodb/internal/connection/tlschannel/async/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/connection/tlschannel/async/package-info.java
@@ -18,7 +18,10 @@
  */
 
 /**
- * This package contains internal functionality that may change at any time.
+ * This package enables the usage of TLS Channel as an {@link
+ * java.nio.channels.AsynchronousByteChannel}.
+ *
+ * <p>This package contains internal functionality that may change at any time.
  */
 @Internal
 package com.mongodb.internal.connection.tlschannel.async;
diff --git a/driver-core/src/main/com/mongodb/internal/connection/tlschannel/package-info.java b/driver-core/src/main/com/mongodb/internal/connection/tlschannel/package-info.java
index e6332466491..d3b738d2593 100644
--- a/driver-core/src/main/com/mongodb/internal/connection/tlschannel/package-info.java
+++ b/driver-core/src/main/com/mongodb/internal/connection/tlschannel/package-info.java
@@ -18,7 +18,16 @@
  */
 
 /**
- * This package contains internal functionality that may change at any time.
+ * TLS Channel is a library that implements a ByteChannel interface to a TLS (Transport Layer
+ * Security) connection. The library delegates all cryptographic operations to the standard Java TLS
+ * implementation: SSLEngine; effectively hiding it behind an easy-to-use streaming API, that allows
+ * to securitize JVM applications with minimal added complexity.
+ *
+ * <p>In other words, a simple library that allows the programmer to have TLS using the same
+ * standard socket API used for plaintext, just like OpenSSL does for C, only for Java, filling a
+ * specially painful missing feature of the standard Java library.
+ *
+ * <p>This package contains internal functionality that may change at any time.
  */
 @Internal
 package com.mongodb.internal.connection.tlschannel;