RDBC-1021: raise ValueError when includes are used in a no_tracking session

session.load(..., includes=...) and query.include() silently discarded includes when no_tracking=True, giving callers a false sense of correctness.
C# raises 'Cannot register includes when NoTracking is enabled'. Added the guard to both the load() path and the query _include() method.

Regression test: test_no_tracking_includes_guard.py verifies that include calls raise ValueError on no-tracking sessions for both load and query paths.

Author: redknightlois

ravendb/documents/session/document_session.py

@@ -315,6 +315,12 @@ def load(
             result = load_operation.get_documents(object_type)
             return result.popitem()[1] if len(result) == 1 else result if result else None
 
+        if self.no_tracking:
+            raise ValueError(
+                "Cannot use includes in a no_tracking session "
+                "(NoTracking is enabled — tracking is required to cache included documents)"
+            )
+
         include_builder = IncludeBuilder(self.conventions)
         includes(include_builder)
 

ravendb/documents/session/query.py

@@ -368,6 +368,11 @@ def __action():
         return MoreLikeThisScope(token, self.__add_query_parameter, __action)
 
     def _include(self, path_or_include_builder: Union[str, IncludeBuilderBase]) -> None:
+        if self._the_session is not None and self._the_session.no_tracking:
+            raise ValueError(
+                "Cannot use includes in a no_tracking session "
+                "(NoTracking is enabled — tracking is required to cache included documents)"
+            )
         if isinstance(path_or_include_builder, str):
             self._document_includes.add(path_or_include_builder)
         elif isinstance(path_or_include_builder, IncludeBuilderBase):

ravendb/tests/session_tests/test_no_tracking_includes_guard.py

@@ -0,0 +1,69 @@
+"""
+No-tracking session: using includes raises when session.no_tracking is True.
+
+C# reference: SlowTests/Issues/RavenDB_21339.cs
+  Using_Includes_In_Non_Tracking_Session_Should_Throw
+"""
+
+from ravendb.documents.session.misc import SessionOptions
+from ravendb.tests.test_base import TestBase
+
+
+class Manager:
+    def __init__(self, name: str = None):
+        self.name = name
+
+
+class Employee:
+    def __init__(self, name: str = None, manager_id: str = None):
+        self.name = name
+        self.manager_id = manager_id
+
+
+class TestRavenDB21339(TestBase):
+    def setUp(self):
+        super().setUp()
+
+    def _populate(self):
+        with self.store.open_session() as session:
+            session.store(Manager(name="Boss"), "managers/1")
+            session.store(Employee(name="Alice", manager_id="managers/1"), "employees/1")
+            session.save_changes()
+
+    def test_load_with_includes_in_no_tracking_session_should_throw(self):
+        """
+        session.load() with an include builder in a no_tracking session must
+        raise an exception, not silently ignore the includes."""
+        self._populate()
+
+        with self.store.open_session(session_options=SessionOptions(no_tracking=True)) as session:
+            with self.assertRaises(Exception) as ctx:
+                session.load(
+                    "employees/1",
+                    Employee,
+                    includes=lambda b: b.include_documents("manager_id"),
+                )
+            self.assertIn("NoTracking", str(ctx.exception))
+
+    def test_query_with_include_in_no_tracking_session_should_throw(self):
+        """
+        query.include() in a no_tracking session must raise an exception,
+        not silently add the include to an unused tracking cache."""
+        self._populate()
+
+        with self.store.open_session(session_options=SessionOptions(no_tracking=True)) as session:
+            with self.assertRaises(Exception) as ctx:
+                list(session.query(object_type=Employee).include("manager_id").wait_for_non_stale_results())
+            self.assertIn("NoTracking", str(ctx.exception))
+
+    def test_document_query_with_include_in_no_tracking_session_should_throw(self):
+        """
+        C# spec: session.Advanced.DocumentQuery<Product>().Include(x => x.Supplier).ToList()
+        in a no_tracking session must raise InvalidOperationException.
+        """
+        self._populate()
+
+        with self.store.open_session(session_options=SessionOptions(no_tracking=True)) as session:
+            with self.assertRaises(Exception) as ctx:
+                list(session.advanced.document_query(object_type=Employee).include("manager_id"))
+            self.assertIn("NoTracking", str(ctx.exception))