tawasuyu/brahman

Sexto módulo siguiendo el patrón establecido. Cambio estructural:
3-way mutual exclusion para los módulos que comparten el outer ring
(transit + synastry + solar_return). Constante OUTER_RING_MODULES
abstrae el grupo para que fase 14+ pueda sumar lunar return / planet
returns sin tocar la lógica del shell.

- engine: PipelineRequest::SolarReturn { target_age_years } +
  build_solar_return_overlay. Llama eternal_astrology::next_return
  (Sun back to natal Sun, ventana ±1.5 años) desde un instante
  ~30 días antes del cumpleaños target. Computa la carta natal
  completa al return_instant (mismo observer + config natales —
  convención clásica) y la apila como Outer + Aspects cross natal ×
  return. z=12/13. Import: `next_return` añadido a la lista de
  re-exports del bridge.
- modules: solar_return::SolarReturnModule (id "solar_return", toggle
  + slider target_age_years 0..120 step 1.0). Registry pasa a 6
  módulos para Natal.
- shell: OUTER_RING_MODULES const con los tres ids; mutual exclusion
  generalizada de pair-wise a N-way (for-loop sobre el slice). Init
  de age en apply_selection ahora incluye solar_return. build_requests
  agrega la rama. Misma estructura que progression/solar_arc en la
  rama de age handling.
- canvas: aspect_endpoints("solar_return") = (bodies, transits). Tres
  loops del outer ring (paint dots, paint glyphs, anillos guía) ahora
  aceptan los tres module_ids.

Probarlo: en el panel, slider "Edad del retorno" en valor entero (ej.
36) + toggle "Activar" = ves la carta del año cuando volviste a tu
Sol natal a los 36, con todos sus planetas en el outer ring y cross
aspects con tu natal. Cambiando el slider podés explorar año por año.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

diff --git a/crates/apps/tahuantinsuyu/src/shell.rs b/crates/apps/tahuantinsuyu/src/shell.rs
index 6870627..c40914e 100644
--- a/crates/apps/tahuantinsuyu/src/shell.rs
+++ b/crates/apps/tahuantinsuyu/src/shell.rs
@@ -144,7 +144,7 @@ impl Shell {
                 //    edad actual. Estos quedan en module_configs como
                 //    valor base si el usuario nunca tocó el slider.
                 self.module_configs.clear();
-                for module_id in ["progression", "solar_arc"] {
+                for module_id in ["progression", "solar_arc", "solar_return"] {
                     let entry = self
                         .module_configs
                         .entry(module_id.into())
@@ -239,6 +239,12 @@ impl Shell {
                 });
             }
         }
+        if module_enabled(&self.module_configs, "solar_return") {
+            let age = self.module_age_or_current("solar_return");
+            requests.push(PipelineRequest::SolarReturn {
+                target_age_years: age,
+            });
+        }
         requests
     }
 
@@ -475,17 +481,13 @@ impl Shell {
                     if let serde_json::Value::Object(map) = entry {
                         map.insert(key.clone(), value.clone());
                     }
-                    // Transit y Synastry comparten el outer ring del
-                    // canvas — son mutuamente excluyentes. Al prender
-                    // uno, apagamos el otro y sincronizamos el panel.
-                    if key == "enabled" && bool_val {
-                        let conflicting = match module_id.as_str() {
-                            "transit" => Some("synastry"),
-                            "synastry" => Some("transit"),
-                            _ => None,
-                        };
-                        if let Some(other) = conflicting {
-                            if module_enabled(&self.module_configs, other) {
+                    // Transit, Synastry y Solar Return comparten el
+                    // outer ring del canvas — son mutuamente excluyentes.
+                    // Al prender uno, apagamos los otros + sync panel +
+                    // persist.
+                    if key == "enabled" && bool_val && OUTER_RING_MODULES.contains(&module_id.as_str()) {
+                        for &other in OUTER_RING_MODULES.iter() {
+                            if other != module_id && module_enabled(&self.module_configs, other) {
                                 set_module_enabled(&mut self.module_configs, other, false);
                                 let other_str = other.to_string();
                                 self.panel.update(cx, |p, cx| {
@@ -496,9 +498,9 @@ impl Shell {
                         }
                     }
                     // Sincronizar visualmente el toggle [T] del canvas
-                    // cuando el cambio afecta el outer ring (transit o
-                    // synastry — ambos lo usan).
-                    if (module_id == "transit" || module_id == "synastry") && key == "enabled" {
+                    // cuando el cambio afecta el outer ring (transit,
+                    // synastry o solar_return).
+                    if OUTER_RING_MODULES.contains(&module_id.as_str()) && key == "enabled" {
                         self.canvas.update(cx, |c, cx| {
                             c.set_layer_visible(LayerKind::Outer, bool_val, cx)
                         });
@@ -520,6 +522,11 @@ impl Shell {
 // Helpers de module_configs
 // =====================================================================
 
+/// Módulos que pintan en el outer ring del canvas — mutuamente
+/// excluyentes a nivel de UI. Al prender uno, los otros se apagan.
+const OUTER_RING_MODULES: &[&str] = &["transit", "synastry", "solar_return"];
+
+
 /// Etiqueta breve para mostrar al elegir una carta en el picker:
 /// `"YYYY-MM-DD · Lugar"` cuando hay lugar, sino solo la fecha.
 fn format_birth_brief(birth: &tahuantinsuyu_model::StoredBirthData) -> String {
diff --git a/crates/modules/tahuantinsuyu/tahuantinsuyu-canvas/src/lib.rs b/crates/modules/tahuantinsuyu/tahuantinsuyu-canvas/src/lib.rs
index 26a2cba..2e68ff4 100644
--- a/crates/modules/tahuantinsuyu/tahuantinsuyu-canvas/src/lib.rs
+++ b/crates/modules/tahuantinsuyu/tahuantinsuyu-canvas/src/lib.rs
@@ -572,7 +572,9 @@ fn render_wheel(
     if visible.get(&LayerKind::Outer).copied().unwrap_or(true) {
         for layer in &render.layers {
             if matches!(layer.kind, LayerKind::Outer)
-                && (layer.module_id == "transit" || layer.module_id == "synastry")
+                && (layer.module_id == "transit"
+                || layer.module_id == "synastry"
+                || layer.module_id == "solar_return")
             {
                 for g in &layer.glyphs {
                     let (x, y) = polar_to_screen(g.deg, asc, rot_offset, radii.transits);
@@ -727,12 +729,12 @@ impl Radii {
 
     /// Resuelve qué radios corresponden a una capa de aspectos según el
     /// `module_id`: natal-natal en `aspects`, cross con cada overlay
-    /// desde `bodies` (extremo natal) al ring del módulo. Synastry
-    /// comparte el outer ring de tránsito (son mutuamente excluyentes
-    /// a nivel de Shell).
+    /// desde `bodies` (extremo natal) al ring del módulo. Synastry y
+    /// Solar Return comparten el outer ring de tránsito (los tres son
+    /// mutuamente excluyentes a nivel de Shell).
     fn aspect_endpoints(&self, module_id: &str) -> (f32, f32) {
         match module_id {
-            "transit" | "synastry" => (self.bodies, self.transits),
+            "transit" | "synastry" | "solar_return" => (self.bodies, self.transits),
             "progression" => (self.bodies, self.progression),
             "solar_arc" => (self.bodies, self.solar_arc),
             _ => (self.aspects, self.aspects),
@@ -945,7 +947,9 @@ fn paint_wheel(
     // si alguno de los dos está prendido, pintamos el slot.
     let outer_active = layers.iter().any(|l| {
         matches!(l.kind, LayerKind::Outer)
-            && (l.module_id == "transit" || l.module_id == "synastry")
+            && (l.module_id == "transit"
+                || l.module_id == "synastry"
+                || l.module_id == "solar_return")
     });
     if outer_active && show(LayerKind::Outer) {
         stroke_circle(
@@ -968,7 +972,9 @@ fn paint_wheel(
         let dot_r = (radii.sign_outer * 0.017).max(2.0);
         for layer in layers {
             if matches!(layer.kind, LayerKind::Outer)
-                && (layer.module_id == "transit" || layer.module_id == "synastry")
+                && (layer.module_id == "transit"
+                || layer.module_id == "synastry"
+                || layer.module_id == "solar_return")
             {
                 for g in &layer.glyphs {
                     let color = with_alpha(planet_color(palette, &g.symbol), 0.85);
diff --git a/crates/modules/tahuantinsuyu/tahuantinsuyu-engine/src/bridge.rs b/crates/modules/tahuantinsuyu/tahuantinsuyu-engine/src/bridge.rs
index 77e12d7..a3ac4b0 100644
--- a/crates/modules/tahuantinsuyu/tahuantinsuyu-engine/src/bridge.rs
+++ b/crates/modules/tahuantinsuyu/tahuantinsuyu-engine/src/bridge.rs
@@ -9,8 +9,8 @@ use std::sync::OnceLock;
 use std::time::Instant;
 
 use eternal_astrology::{
-    find_aspects, find_synastry_aspects, secondary_progression, solar_arc_true, Aspect,
-    AspectKind as EAspectKind, BirthData, BodySet, ChartConfig, HouseSystem as EHouseSystem,
+    find_aspects, find_synastry_aspects, next_return, secondary_progression, solar_arc_true,
+    Aspect, AspectKind as EAspectKind, BirthData, BodySet, ChartConfig, HouseSystem as EHouseSystem,
     NatalChart, OrbTable, Zodiac as EZodiac,
 };
 use eternal_sky::{Ayanamsha, Body, EphemerisSession, Instant as ESInstant, Observer, SessionConfig};
@@ -264,6 +264,15 @@ pub fn compose(
             crate::PipelineRequest::Synastry { partner_chart } => {
                 build_synastry_overlay(&natal, partner_chart, &mut render)?;
             }
+            crate::PipelineRequest::SolarReturn { target_age_years } => {
+                build_solar_return_overlay(
+                    &natal,
+                    &config_e,
+                    observer,
+                    *target_age_years,
+                    &mut render,
+                )?;
+            }
         }
     }
 
@@ -531,6 +540,100 @@ fn build_synastry_overlay(
     Ok(())
 }
 
+/// Helper: agrega al `RenderModel` las capas del overlay de Solar
+/// Return — la carta natal completa computada al instante en que el
+/// Sol vuelve a su posición natal en el año pedido. Esa nueva carta
+/// va en el anillo externo (compartido con Transit/Synastry —
+/// mutuamente excluyentes a nivel de Shell). Cross aspects natal ×
+/// return.
+fn build_solar_return_overlay(
+    natal: &NatalChart,
+    config_e: &ChartConfig,
+    observer: Observer,
+    target_age_years: f64,
+    render: &mut RenderModel,
+) -> Result<(), EngineError> {
+    let session = session()?;
+    let natal_sun = natal.placement(Body::Sun).ok_or_else(|| {
+        EngineError::Eternal("natal chart sin Sol — Solar Return imposible".into())
+    })?;
+    let natal_sun_lon = natal_sun.longitude.longitude_rad();
+
+    // Buscar el próximo retorno desde un punto razonable antes del
+    // cumpleaños del año target. Restamos 30 días para garantizar que
+    // el retorno (que cae ~en la fecha de nacimiento) quede DENTRO de
+    // la ventana de búsqueda.
+    const TROPICAL_YEAR_SECS: f64 = 365.242190 * 86400.0;
+    let after_seconds = (target_age_years * 365.242190 - 30.0) * 86400.0;
+    let after_utc = natal
+        .birth
+        .instant
+        .utc()
+        .add_seconds(after_seconds.max(-TROPICAL_YEAR_SECS * 2.0));
+    let after = ESInstant::from_utc(after_utc);
+
+    let return_instant = next_return(session, Body::Sun, natal_sun_lon, after, None)
+        .map_err(|e| EngineError::Eternal(format!("next_return Sun: {:?}", e)))?;
+
+    // La carta del retorno se computa al return_instant con el mismo
+    // observer y config natales (convención clásica: solar return
+    // tropical en la ciudad de nacimiento).
+    let return_birth = BirthData::new(return_instant, observer);
+    let return_chart = NatalChart::compute(&return_birth, config_e, session).map_err(|e| {
+        EngineError::Eternal(format!("NatalChart::compute (solar return): {:?}", e))
+    })?;
+
+    let glyphs: Vec<Glyph> = return_chart
+        .placements
+        .iter()
+        .map(|p| Glyph {
+            deg: p.longitude.longitude_deg() as f32,
+            symbol: body_symbol(p.body).into(),
+            annotation: Some(format!("{:.1}°", p.longitude.degree_in_sign_decimal())),
+            retrograde: p.longitude_rate_rad_per_day < 0.0,
+            house: Some(p.house_number),
+        })
+        .collect();
+    render.layers.push(Layer {
+        module_id: "solar_return".into(),
+        kind: LayerKind::Outer,
+        ring: 0.82,
+        z: 12,
+        geometry: Geometry::GlyphsOnly,
+        glyphs,
+    });
+
+    let cross = find_synastry_aspects(
+        natal,
+        &return_chart,
+        &OrbTable::modern_western(),
+        EAspectKind::MAJORS,
+    );
+    let cross_lines: Vec<LineSeg> = cross
+        .iter()
+        .filter_map(|a| {
+            let n_p = natal.placement(a.person_a_body)?;
+            let r_p = return_chart.placement(a.person_b_body)?;
+            let opacity = orb_to_opacity(a.orb_abs_deg(), a.kind);
+            Some(LineSeg {
+                from_deg: n_p.longitude.longitude_deg() as f32,
+                to_deg: r_p.longitude.longitude_deg() as f32,
+                kind: aspect_kind_id(a.kind).into(),
+                opacity: opacity * 0.8,
+            })
+        })
+        .collect();
+    render.layers.push(Layer {
+        module_id: "solar_return".into(),
+        kind: LayerKind::Aspects,
+        ring: 0.0,
+        z: 13,
+        geometry: Geometry::Lines(cross_lines),
+        glyphs: Vec::new(),
+    });
+    Ok(())
+}
+
 // =====================================================================
 // NatalChart → RenderModel
 // =====================================================================
diff --git a/crates/modules/tahuantinsuyu/tahuantinsuyu-engine/src/lib.rs b/crates/modules/tahuantinsuyu/tahuantinsuyu-engine/src/lib.rs
index f11f802..a24b564 100644
--- a/crates/modules/tahuantinsuyu/tahuantinsuyu-engine/src/lib.rs
+++ b/crates/modules/tahuantinsuyu/tahuantinsuyu-engine/src/lib.rs
@@ -191,6 +191,13 @@ pub enum PipelineRequest {
     Synastry {
         partner_chart: Box<Chart>,
     },
+    /// `module_id = "solar_return"` — carta natal fresca al instante
+    /// del próximo retorno solar para la edad pedida (Sun back to
+    /// natal Sun). Anillo externo compartido con Transit/Synastry
+    /// — mutuamente excluyentes los tres a nivel de Shell.
+    SolarReturn {
+        target_age_years: f64,
+    },
 }
 
 /// Composición canónica: carta natal + todos los overlays pedidos.
diff --git a/crates/modules/tahuantinsuyu/tahuantinsuyu-modules/src/lib.rs b/crates/modules/tahuantinsuyu/tahuantinsuyu-modules/src/lib.rs
index 3ff3fe7..d3eb15a 100644
--- a/crates/modules/tahuantinsuyu/tahuantinsuyu-modules/src/lib.rs
+++ b/crates/modules/tahuantinsuyu/tahuantinsuyu-modules/src/lib.rs
@@ -136,6 +136,7 @@ impl Registry {
         r.register(Box::new(progression::ProgressionModule));
         r.register(Box::new(solar_arc::SolarArcModule));
         r.register(Box::new(synastry::SynastryModule));
+        r.register(Box::new(solar_return::SolarReturnModule));
         r
     }
 
@@ -393,6 +394,58 @@ pub mod synastry {
     }
 }
 
+// =====================================================================
+// SolarReturnModule — carta del año en curso (Sun back to natal Sun)
+// =====================================================================
+
+pub mod solar_return {
+    use super::*;
+
+    /// Computa la carta natal completa al instante del próximo retorno
+    /// solar para la edad pedida. Comparte el outer ring con Transit y
+    /// Synastry — mutuamente excluyentes a nivel de Shell.
+    pub struct SolarReturnModule;
+
+    impl Module for SolarReturnModule {
+        fn id(&self) -> &'static str {
+            "solar_return"
+        }
+        fn label(&self) -> &'static str {
+            "Retorno solar"
+        }
+        fn description(&self) -> &'static str {
+            "Carta del año — Sol de vuelta a su posición natal."
+        }
+        fn applies_to(&self, kind: ChartKind) -> bool {
+            matches!(kind, ChartKind::Natal)
+        }
+        fn enabled_by_default(&self) -> bool {
+            false
+        }
+        fn controls(&self) -> Vec<Control> {
+            vec![
+                Control::Toggle {
+                    key: "enabled".into(),
+                    label: "Activar".into(),
+                    default: false,
+                    hotkey: None,
+                },
+                Control::Slider {
+                    key: "target_age_years".into(),
+                    label: "Edad del retorno".into(),
+                    min: 0.0,
+                    max: 120.0,
+                    step: 1.0,
+                    default: 30.0,
+                },
+            ]
+        }
+        fn compute_layers(&self, _chart: &Chart, _cfg: &serde_json::Value) -> Vec<Layer> {
+            Vec::new()
+        }
+    }
+}
+
 // =====================================================================
 // SolarArcModule — Solar Arc dirigido (true progressed Sun)
 // =====================================================================
@@ -458,8 +511,9 @@ mod tests {
         assert!(r.find("progression").is_some());
         assert!(r.find("solar_arc").is_some());
         assert!(r.find("synastry").is_some());
-        // Natal kind tiene 5 módulos aplicables.
-        assert_eq!(r.for_kind(ChartKind::Natal).len(), 5);
+        assert!(r.find("solar_return").is_some());
+        // Natal kind tiene 6 módulos aplicables.
+        assert_eq!(r.for_kind(ChartKind::Natal).len(), 6);
         assert!(r.for_kind(ChartKind::Synastry).is_empty());
     }
 }