test(nam): guard model-name recall + document deferred automation (#246)

Author: OpenSauce

rustortion-core/src/preset/stage_config.rs

@@ -197,3 +197,50 @@ impl StageConfig {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The plugin persists its chain as `Vec<StageConfig>` JSON in `chain_state`
+    /// (nih-plug `#[persist]`), and a NAM stage stores its model BY NAME. This is
+    /// the exact path that recalls a selected model when a DAW project reopens, so
+    /// guard it: the model name (and the other NAM fields) must survive a JSON
+    /// round-trip.
+    #[test]
+    fn nam_model_name_survives_chain_state_round_trip() {
+        let chain = vec![
+            StageConfig::Nam(NamConfig {
+                model_name: Some("S-[AMP] Divine Sheep #04".to_owned()),
+                input_gain_db: 3.0,
+                output_gain_db: -2.0,
+                mix: 0.75,
+                bypassed: true,
+            }),
+            // A passthrough NAM stage (no model) must round-trip as `None`, not "".
+            StageConfig::Nam(NamConfig::default()),
+        ];
+
+        let json = serde_json::to_string(&chain).expect("serialize chain_state");
+        let restored: Vec<StageConfig> =
+            serde_json::from_str(&json).expect("deserialize chain_state");
+
+        assert_eq!(restored.len(), 2);
+        let StageConfig::Nam(cfg) = &restored[0] else {
+            panic!("expected a NAM stage at index 0");
+        };
+        assert_eq!(cfg.model_name.as_deref(), Some("S-[AMP] Divine Sheep #04"));
+        // Small fixed tolerance — `f32::EPSILON` is the spacing near 1.0, not a
+        // general-purpose comparison bound.
+        const TOL: f32 = 1e-6;
+        assert!((cfg.input_gain_db - 3.0).abs() < TOL);
+        assert!((cfg.output_gain_db - (-2.0)).abs() < TOL);
+        assert!((cfg.mix - 0.75).abs() < TOL);
+        assert!(cfg.bypassed);
+
+        let StageConfig::Nam(cfg) = &restored[1] else {
+            panic!("expected a NAM stage at index 1");
+        };
+        assert_eq!(cfg.model_name, None);
+    }
+}

rustortion-plugin/src/params.rs

@@ -481,6 +481,15 @@ impl Default for EqSlotParams {
     }
 }
 
+/// Per-slot NAM params — intentionally **no** `model` parameter here.
+///
+/// The selected model is stored by NAME in `NamConfig.model_name` inside the
+/// serialized `chain_state`, so it persists with and recalls from the DAW project
+/// (the chain is rebuilt and each NAM stage resolves its model by name on load).
+/// Name-based recall is robust against the model list reordering. Exposing model
+/// choice as a host-automatable param is deferred — it needs a general slot<->stage
+/// param pump (and a background reload, since switching models loads a neural net
+/// off the audio thread), with no clean NAM-only slice.
 #[derive(Params)]
 pub struct NamSlotParams {
     #[id = "input_gain_db"]