fix(R-009): tighten fixupDocumentDbExplain JSDoc, drop dead fallback

Updated JSDoc to document that the input is mutated in place and the
return value is the same reference. Removed the unnecessary
'| undefined' from the type assertions in ClustersClient since
fixupDocumentDbExplain only returns undefined when its input is
undefined (which cannot happen in these call sites).

Author: tnaum-ms

src/documentdb/ClustersClient.ts

@@ -1116,7 +1116,7 @@ export class ClustersClient {
         }
         const result = await this._llmEnhancedFeatureApis.explainFind(databaseName, collectionName, verbosity, options);
         const metadata = await this.getClusterMetadata();
-        return (fixupDocumentDbExplain(result, metadata) as ExplainResult | undefined) ?? result;
+        return (fixupDocumentDbExplain(result, metadata) as ExplainResult) ?? result;
     }
 
     /**
@@ -1132,7 +1132,7 @@ export class ClustersClient {
         }
         const result = await this._llmEnhancedFeatureApis.explainAggregate(databaseName, collectionName, pipeline);
         const metadata = await this.getClusterMetadata();
-        return (fixupDocumentDbExplain(result, metadata) as ExplainResult | undefined) ?? result;
+        return (fixupDocumentDbExplain(result, metadata) as ExplainResult) ?? result;
     }
 
     /**

src/documentdb/utils/fixupDocumentDbExplain.ts

@@ -26,10 +26,12 @@ export function isAzureDocumentDb(metadata: ClusterMetadata | undefined): boolea
 }
 
 /**
- * Patches the explain result to correct `totalKeysExamined` / `keysExamined` for
- * Azure DocumentDB when no index is used.
+ * Patches the explain result **in place** to correct `totalKeysExamined` / `keysExamined`
+ * for Azure DocumentDB when no index is used.
  *
- * @returns The (potentially mutated) explain result, or undefined if input was undefined.
+ * The input document is mutated directly; the return value is the same reference.
+ *
+ * @returns The mutated explain result, or undefined if input was undefined.
  */
 export function fixupDocumentDbExplain(
     explainResult: Document | undefined,