feat(generator): add shutdown lifecycle event (#97)

## Summary
- emit shutdown event when the generator loop fully exits
- have ServeLoop evict generators based on `.shutdown`
- update generator docs with shutdown lifecycle event
- expect shutdown frames in tests

## Testing
- `./scripts/check.sh`
- `cd docs && npm run build`

docs/src/content/docs/reference/generators.mdx

···
 | `<topic>.recv`        | Output value from the generator         |
 | `<topic>.stop` | Generator pipeline has stopped. The \`meta.reason\` field is a string enum with values `finished`, `error`, `terminate` and `update`. When `finished` or `error`, the pipeline will be restarted automatically; `terminate` means it was stopped manually and the generator loop for this topic/context will shut down. `update` indicates the generator reloaded due to a new `.spawn` frame. |
 | `<topic>.parse.error` | Script failed to parse |
+| `<topic>.shutdown` | Generator loop has fully exited; ServeLoop evicts it |
 
-All events include `source_id` which is the ID of the generator instance. When a `.stop` frame has `meta.reason` set to `update`, it also includes `update_id` referencing the spawn that triggered the reload.
+All events include `source_id` which is the ID of the generator instance. When a `.stop` frame has `meta.reason` set to `update`, it also includes `update_id` referencing the spawn that triggered the reload. ServeLoop evicts a generator when it receives a `<topic>.shutdown` frame.
 
 ## Configuration Options
 

src/generators/generator.rs

···
             )?;
         }
 
-        GeneratorEventKind::Shutdown => { /* no frame */ }
+        GeneratorEventKind::Shutdown => {
+            store.append(
+                Frame::builder(format!("{}.shutdown", loop_ctx.topic), loop_ctx.context_id)
+                    .meta(json!({ "source_id": task.id.to_string() }))
+                    .build(),
+            )?;
+        }
     }
 
     Ok(GeneratorEvent {
···
             &task,
             GeneratorEventKind::Stop(reason.clone()),
         );
-        if matches!(reason, StopReason::Terminate) {
+        if matches!(reason, StopReason::Terminate) || matches!(reason, StopReason::Error { .. }) {
+            let _ = emit_event(&store, &loop_ctx, &task, GeneratorEventKind::Shutdown);
             break;
         } else if let StopReason::Update { .. } = reason {
             if let Some(nt) = next_task.take() {

src/generators/serve.rs

···
             continue;
         }
 
-        if let Some(prefix) = frame.topic.strip_suffix(".stop") {
-            if let Some(reason) = frame
-                .meta
-                .as_ref()
-                .and_then(|m| m.get("reason"))
-                .and_then(|v| v.as_str())
-            {
-                if reason == "terminate" || reason == "error" {
-                    let key = (prefix.to_string(), frame.context_id);
-                    active.remove(&key);
-                }
-            }
+        if let Some(prefix) = frame.topic.strip_suffix(".shutdown") {
+            active.remove(&(prefix.to_string(), frame.context_id));
             continue;
         }
     }

src/generators/tests.rs

···
 use crate::generators::generator::emit_event;
 use crate::nu::ReturnOptions;
 use nu_protocol;
-use scru128::{self, Scru128Id};
+use scru128;
 use std::time::Duration;
 use tempfile::TempDir;
 
···
     let stop = recver.recv().await.unwrap();
     assert_eq!(stop.topic, "sleeper.stop");
     assert_eq!(stop.meta.unwrap()["reason"], "terminate");
+    assert_eq!(recver.recv().await.unwrap().topic, "sleeper.shutdown");
 
     store
         .append(Frame::builder("sleeper.spawn", ctx.id).hash(hash).build())
···
     let frame = recver.recv().await.unwrap();
     assert_eq!(frame.topic, "echo.stop");
     assert_eq!(frame.meta.unwrap()["reason"], "terminate");
+    assert_eq!(recver.recv().await.unwrap().topic, "echo.shutdown");
 
     store
         .append(Frame::builder("echo.send", ctx.id).build())
···
     let stop1 = recver.recv().await.unwrap();
     assert_eq!(stop1.topic, "gen1.stop");
     assert_eq!(stop1.meta.unwrap()["reason"], "terminate");
+    let shutdown1 = recver.recv().await.unwrap();
+    assert_eq!(shutdown1.topic, "gen1.shutdown");
 
     let msg_hash = store.cas_insert("ping").await.unwrap();
     store
···
     )
     .unwrap();
     assert!(matches!(ev.kind, GeneratorEventKind::Stop(_)));
+
+    let _ = emit_event(&store, &loop_ctx, &task, GeneratorEventKind::Shutdown).unwrap();
+    assert_eq!(store.head("helper.shutdown", ZERO_CONTEXT).is_some(), true);
 }