fix(lsp): address race condition and misleading comments in version tracking

Addresses three Copilot review comments:

1. Fixed TOCTOU race in validate_from_content_and_publish: capture version
   at the same time as content snapshot to ensure diagnostics are published
   with the version matching the content they were validated against, not a
   newer version from concurrent did_change events.

2. Corrected misleading comments in handle_did_open/did_change about lock
   guarantees. The comments suggested locks prevent readers from seeing
   inconsistency, but that's only true if readers atomically capture both
   values together (which they now do).

3. Clarified integration test comment to explain why it doesn't assert
   version field in publish_diagnostics (requires consuming socket messages).
   Referenced unit tests in backend/tests.rs that verify version lifecycle.

Author: avifenesh

crates/agnix-lsp/src/backend.rs

@@ -200,13 +200,15 @@ impl Backend {
             }
         }
 
-        // Get content from cache
-        let (content, expected_content) = {
+        // Get content from cache and capture version at same time to avoid TOCTOU
+        // between content validation and version publish
+        let (content, expected_content, captured_version) = {
             let docs = self.documents.read().await;
             match docs.get(&uri) {
                 Some(cached) => {
                     let snapshot = Arc::clone(cached);
-                    (Arc::clone(&snapshot), Some(snapshot))
+                    let version = self.get_document_version(&uri).await;
+                    (Arc::clone(&snapshot), Some(snapshot), version)
                 }
                 None => {
                     // Fall back to file-based validation
@@ -267,8 +269,9 @@ impl Backend {
             return;
         }
 
-        // Read version just-in-time to minimize TOCTOU window
-        let version = self.get_document_version(&uri).await;
+        // Use version captured at time of content snapshot to avoid publishing
+        // newer version with older (already-validated) diagnostics
+        let version = captured_version;
         self.client
             .publish_diagnostics(uri, diagnostics, version)
             .await;

crates/agnix-lsp/src/backend/events.rs

@@ -14,8 +14,9 @@ impl Backend {
             std::borrow::Cow::Borrowed(_) => raw,
             std::borrow::Cow::Owned(normalized) => normalized,
         };
-        // Acquire both locks before releasing either so readers never see a
-        // state where content is updated but version is not (or vice versa).
+        // Acquire both locks atomically to update content and version together.
+        // Readers that need both values must capture them in a single operation
+        // (see validate_from_content_and_publish).
         {
             let mut docs = self.documents.write().await;
             let mut versions = self.document_versions.write().await;
@@ -38,8 +39,9 @@ impl Backend {
                 std::borrow::Cow::Borrowed(_) => raw,
                 std::borrow::Cow::Owned(normalized) => normalized,
             };
-            // Acquire both locks before releasing either so readers never see a
-            // state where content is updated but version is not (or vice versa).
+            // Acquire both locks atomically to update content and version together.
+            // Readers that need both values must capture them in a single operation
+            // (see validate_from_content_and_publish).
             {
                 let mut docs = self.documents.write().await;
                 let mut versions = self.document_versions.write().await;

crates/agnix-lsp/tests/lsp_integration.rs

@@ -1579,7 +1579,12 @@ mod document_version_tests {
         // This test exercises the version lifecycle through the LanguageServer
         // trait boundary and uses hover as a behavioral indicator of document
         // cache state (hover returns Some when cached, None after close).
-
+        //
+        // Note: This test verifies that versions are tracked and available
+        // for publishing. The actual assertion that diagnostics are published
+        // with the correct version field requires consuming LSP notifications
+        // from the socket. See backend/tests.rs for unit tests that verify
+        // version lifecycle (test_document_version_tracked_on_open, etc.).
         // Phase 1: Open with version 1
         service
             .inner()