docs: document PlaygroundEvaluator lifecycle after killWorker (#645) (#706)

Author: tnaum-ms

src/commands/playground/executePlaygroundCode.ts

@@ -169,6 +169,9 @@ export async function executePlaygroundCode(
 
                 token.onCancellationRequested(() => {
                     cancelled = true;
+                    // killWorker() terminates the worker thread but the evaluator
+                    // instance stays in the pool. The next evaluate() call will
+                    // detect the dead worker and transparently spawn a new one.
                     evaluator?.killWorker();
                 });
 

src/documentdb/playground/PlaygroundEvaluator.ts

@@ -28,6 +28,34 @@ import { type MainToWorkerMessage, type SerializableMongoClientOptions, type Wor
  *
  * The public API is unchanged from the in-process evaluator:
  * `evaluate(connection, code) → Promise<ExecutionResult>`
+ *
+ * ## Lifecycle
+ *
+ * The evaluator instance and the worker thread have **independent lifecycles**:
+ *
+ * ```
+ * Evaluator instance        Worker thread
+ * ─────────────────         ─────────────
+ * new PlaygroundEvaluator()
+ *   └─ evaluate() ────────► spawn + connect
+ *   └─ evaluate() ────────► reuse (no re-auth)
+ *   └─ killWorker() ──────► terminate
+ *   └─ evaluate() ────────► re-spawn + re-connect
+ *   └─ shutdown() ────────► graceful close
+ * ```
+ *
+ * After `killWorker()` (called on user cancellation), the evaluator instance
+ * stays registered in the per-cluster evaluator pool (`evaluators` Map in
+ * `executePlaygroundCode.ts`). The next `evaluate()` call detects that the
+ * worker is dead and transparently spawns a new one. Session telemetry
+ * (`_sessionId`, `_sessionEvalCount`) resets on each worker spawn, so a
+ * killed-and-respawned worker behaves like a fresh evaluator session.
+ *
+ * The evaluator is only removed from the pool by `shutdownEvaluator()` (when
+ * all playground documents for the cluster close) or by `disposeEvaluators()`
+ * (on extension deactivation). `shutdownEvaluator()` calls `shutdown()`, while
+ * `disposeEvaluators()` calls `dispose()`. Both paths gracefully close the
+ * worker before removing the evaluator.
  */
 export class PlaygroundEvaluator implements vscode.Disposable {
     private readonly _workerManager: WorkerSessionManager;