tawasuyu/brahman

1//! `tahuantinsuyu-engine` — bridge entre el modelo agnóstico y
2//! `eternal-astrology`.
3//!
4//! Recibe un `Chart` del modelo + un `ChartKind` y devuelve un
5//! [`RenderModel`] que describe la geometría a pintar **sin** acoplar
6//! el canvas a tipos de la librería astronómica. El canvas habla
7//! grados decimales, radios normalizados y kinds simbólicos.
8//!
9//! ## Por qué un RenderModel intermedio
10//!
11//! 1. El canvas no debería caer si cambia el shape de `NatalChart`
12//!    upstream.
13//! 2. Tests del canvas: podemos generar `RenderModel`s sintéticos sin
14//!    arrancar eternal.
15//! 3. Cada `ChartKind` produce el mismo shape genérico → el render
16//!    coordina N módulos sin saber qué calcularon.
17//!
18//! ## Feature `eternal-bridge`
19//!
20//! - **on** (default): [`compute`] abre una `EphemerisSession` VSOP2013
21//!   compartida y corre la pipeline real.
22//! - **off**: [`compute`] cae a [`compute_mock`] — útil para tests +
23//!   builds sin eternal checked out.
24
25#![forbid(unsafe_code)]
26#![warn(rust_2018_idioms)]
27
28use serde::{Deserialize, Serialize};
29use thiserror::Error;
30
31pub use tahuantinsuyu_model::{Chart, ChartId, ChartKind};
32
33// `Chart` reexportado arriba es lo que `PipelineRequest::Synastry`
34// transporta — el caller (shell) lee del Store y pasa el Chart entero
35// para que el bridge construya su NatalChart en eternal.
36
37#[cfg(feature = "eternal-bridge")]
38mod bridge;
39#[cfg(feature = "eternal-bridge")]
40mod dignity;
41#[cfg(feature = "eternal-bridge")]
42pub mod svg_export;
43
44// =====================================================================
45// RenderModel — lo que el canvas necesita pintar
46// =====================================================================
47
48/// Resultado agnóstico de un cómputo astrológico, listo para renderizar.
49#[derive(Debug, Clone, Serialize, Deserialize)]
50pub struct RenderModel {
51    pub chart_id: ChartId,
52    pub chart_kind: ChartKind,
53    pub title: String,
54    #[serde(default)]
55    pub subtitle: Option<String>,
56    pub compute_ms: u64,
57
58    // ─── Ángulos del chart (grados eclípticos, 0..360) ───────────────
59    /// Ascendente — punto fijo de rotación del lienzo. La rueda se gira
60    /// de modo que el Asc cae a las 9 (lado izquierdo).
61    pub ascendant_deg: f32,
62    pub midheaven_deg: f32,
63    pub descendant_deg: f32,
64    pub imum_coeli_deg: f32,
65
66    /// Capas a pintar. Orden = z-order ascendente.
67    pub layers: Vec<Layer>,
68    /// Metadata humana por overlay activo (transit, progresión,
69    /// sinastría, retorno...). Vacío para una carta natal pura. La UI
70    /// la pinta como badges en el footer.
71    #[serde(default)]
72    pub overlays: Vec<OverlayMeta>,
73    /// Lista paralela a las LineSeg de aspectos — uno por aspecto
74    /// natal o cross. Ordenado por `orb_deg` ascendente (los más
75    /// cerrados primero). La UI lo usa para la lista textual.
76    #[serde(default)]
77    pub aspect_summary: Vec<AspectSummary>,
78}
79
80/// Etiqueta legible de un overlay para el footer del canvas. La engine
81/// la pushea desde cada `build_*_overlay`; el canvas solo lee y pinta.
82#[derive(Debug, Clone, Serialize, Deserialize)]
83pub struct OverlayMeta {
84    pub module_id: String,
85    /// Etiqueta corta — ej. "Tránsito ahora", "Progresión 38.2a",
86    /// "Sinastría · Ana", "Saturn return 29a".
87    pub label: String,
88}
89
90/// Resumen textual de un aspecto para listas legibles. La engine lo
91/// emite en paralelo con las `LineSeg` de la capa de aspectos, así
92/// el canvas no tiene que re-derivar nombres de cuerpos desde grados.
93#[derive(Debug, Clone, Serialize, Deserialize)]
94pub struct AspectSummary {
95    /// Module al que pertenece — "natal", "transit", "synastry",
96    /// "progression", "solar_arc", "planetary_return".
97    pub module_id: String,
98    /// Identificador agnóstico del cuerpo "a" — "sun", "moon", etc.
99    pub from_body: String,
100    pub to_body: String,
101    /// Identificador del aspecto — "conjunction", "trine", etc.
102    pub kind: String,
103    pub orb_deg: f64,
104    /// `Some(true)` = applying, `Some(false)` = separating. `None` para
105    /// cross-aspects (sinastría/return) donde no se computa.
106    #[serde(default)]
107    pub applying: Option<bool>,
108}
109
110#[derive(Debug, Clone, Serialize, Deserialize)]
111pub struct Layer {
112    pub module_id: String,
113    pub kind: LayerKind,
114    /// Radio normalizado [0, 1] sobre el lienzo — el canvas lo convierte
115    /// a píxeles. Permite stack de anillos.
116    pub ring: f32,
117    #[serde(default)]
118    pub z: i32,
119    pub geometry: Geometry,
120    #[serde(default)]
121    pub glyphs: Vec<Glyph>,
122}
123
124#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
125#[serde(rename_all = "snake_case")]
126pub enum LayerKind {
127    SignDial,
128    Houses,
129    Bodies,
130    Aspects,
131    Lots,
132    FixedStars,
133    Midpoints,
134    Outer,
135    Custom,
136}
137
138#[derive(Debug, Clone, Serialize, Deserialize)]
139pub enum Geometry {
140    GlyphsOnly,
141    /// Anillo dividido en sectores. `cusps_deg` son los grados
142    /// zodiacales donde van las divisiones radiales.
143    Ring { cusps_deg: Vec<f32> },
144    Lines(Vec<LineSeg>),
145    Points(Vec<PointMark>),
146}
147
148#[derive(Debug, Clone, Serialize, Deserialize)]
149pub struct LineSeg {
150    /// Grados zodiacales del extremo "a".
151    pub from_deg: f32,
152    /// Grados zodiacales del extremo "b".
153    pub to_deg: f32,
154    /// Categoría simbólica (`"conjunction"`, `"trine"`, …) — el theme la
155    /// resuelve a color.
156    pub kind: String,
157    pub opacity: f32,
158}
159
160#[derive(Debug, Clone, Serialize, Deserialize)]
161pub struct PointMark {
162    pub deg: f32,
163    pub label: String,
164    pub tag: String,
165}
166
167#[derive(Debug, Clone, Default, Serialize, Deserialize)]
168pub struct Glyph {
169    /// Grado eclíptico [0, 360).
170    pub deg: f32,
171    /// Glyph simbólico — el theme/canvas lo mapea a unicode o imagen.
172    /// Ej: `"sun"`, `"moon"`, `"aries"`, `"asc"`, `"mc"`.
173    pub symbol: String,
174    #[serde(default)]
175    pub annotation: Option<String>,
176    #[serde(default)]
177    pub retrograde: bool,
178    #[serde(default)]
179    pub house: Option<u8>,
180    /// Marker de dignidad esencial, set solo cuando
181    /// `NatalOptions::show_dignities` está activo: `"+"` (domicilio),
182    /// `"·"` (exaltación), `"−"` (exilio), `"*"` (caída).
183    #[serde(default)]
184    pub dignity_marker: Option<String>,
185}
186
187// =====================================================================
188// Errores
189// =====================================================================
190
191#[derive(Debug, Error)]
192pub enum EngineError {
193    #[error("bridge a eternal-astrology no disponible (recompilá con feature `eternal-bridge`)")]
194    BridgeDisabled,
195    #[error("model: {0}")]
196    Model(#[from] tahuantinsuyu_model::ModelError),
197    #[error("eternal: {0}")]
198    Eternal(String),
199    #[error("kind {0:?} todavía no implementado")]
200    UnsupportedKind(ChartKind),
201}
202
203// =====================================================================
204// API pública
205// =====================================================================
206
207/// Pedidos que el host (Shell) eleva a la engine para componer un
208/// `RenderModel`. La capa natal **siempre** se computa; estos requests
209/// son **overlays adicionales**.
210///
211/// Cada variante mapea 1-a-1 con un Module declarado en
212/// `tahuantinsuyu-modules` por id string. Esto deja la engine como
213/// dueña única del cómputo (no depende del trait Module — los módulos
214/// son sólo metadata + UI controls).
215/// Módulos overlay que pintan en el mismo slot (outer ring del wheel)
216/// y por lo tanto son **mutuamente excluyentes** a nivel de UI: al
217/// prender uno, el shell debe apagar los otros. Single source of truth
218/// — el shell y el canvas leen de acá en vez de hardcodear listas.
219pub const OUTER_RING_MODULES: &[&str] = &["transit", "synastry", "planetary_return"];
220
221#[derive(Debug, Clone)]
222pub enum PipelineRequest {
223    /// `module_id = "transit"` — anillo externo con planetas al
224    /// instante actual (reloj de pared) + cross aspects natal × transit.
225    Transit,
226    /// `module_id = "progression"` — anillo interno con los planetas
227    /// progresados (método secundario "día por año") a la edad pedida
228    /// + cross aspects natal × progresada.
229    SecondaryProgression {
230        /// Edad simbólica en años a la que avanzar la carta. Para "la
231        /// edad de hoy", el shell la calcula a partir de `birth_data` +
232        /// `SystemTime::now`.
233        target_age_years: f64,
234    },
235    /// `module_id = "solar_arc"` — Solar Arc dirigido (default = "true
236    /// progressed Sun"): cada cuerpo y cada cusp natal se desplazan por
237    /// el mismo arco ≈ 1° por año de vida. Anillo interno bien adentro
238    /// + cross aspects natal × dirigida.
239    SolarArc {
240        target_age_years: f64,
241    },
242    /// `module_id = "synastry"` — bi-wheel: la natal en el centro, la
243    /// carta del partner en el anillo externo (compartido con Transit
244    /// — mutuamente excluyentes), cross aspects natal × partner.
245    /// El partner viene como `Chart` completo del shell.
246    Synastry {
247        partner_chart: Box<Chart>,
248    },
249    /// `module_id = "planetary_return"` — carta natal fresca al
250    /// instante del próximo retorno del cuerpo elegido a su posición
251    /// natal, para la edad pedida. Sun = retorno solar anual, Moon =
252    /// mensual, Júpiter/Saturno = generacionales. Anillo externo
253    /// compartido con Transit/Synastry — mutuamente excluyentes a
254    /// nivel de Shell.
255    PlanetaryReturn {
256        /// Identificador agnóstico del cuerpo ("sun", "moon",
257        /// "jupiter", …). El bridge lo mapea a `eternal_sky::Body`.
258        body: String,
259        target_age_years: f64,
260    },
261    /// `module_id = "midpoints"` — anillo de puntos medios entre pares
262    /// de cuerpos natales. Por simplicidad filtramos a los que
263    /// involucran al Sol o a la Luna (~10 puntos).
264    Midpoints,
265}
266
267/// Opciones que afectan la pasada natal (qué aspectos pintar, qué
268/// multiplicador de orbe usar). Es independiente de los overlays.
269#[derive(Debug, Clone)]
270pub struct NatalOptions {
271    /// Incluir aspectos mayores (conj/opp/trine/square/sextile).
272    pub show_majors: bool,
273    /// Incluir aspectos menores (quincunx/semi-sextile/etc).
274    pub show_minors: bool,
275    /// Multiplicador uniforme sobre los orbes default. `1.0` = orbes
276    /// modern_western; `0.5` = tight; `2.0` = wide.
277    pub orb_multiplier: f64,
278    /// Si `true`, anota cada cuerpo natal con su dignidad esencial
279    /// (domicilio +, exaltación ·, exilio −, caída *). El canvas lo
280    /// renderea como sufijo del glifo.
281    pub show_dignities: bool,
282}
283
284impl Default for NatalOptions {
285    fn default() -> Self {
286        Self {
287            show_majors: true,
288            show_minors: false,
289            orb_multiplier: 1.0,
290            show_dignities: false,
291        }
292    }
293}
294
295/// Composición canónica: carta natal + todos los overlays pedidos.
296/// Equivalente a `compose_with_options` con `NatalOptions::default()`.
297pub fn compose(
298    chart: &Chart,
299    offset_minutes: i64,
300    requests: &[PipelineRequest],
301) -> Result<RenderModel, EngineError> {
302    compose_with_options(chart, offset_minutes, requests, &NatalOptions::default())
303}
304
305/// Variante que permite controlar qué aspectos natales se computan y
306/// con qué multiplicador de orbe.
307pub fn compose_with_options(
308    chart: &Chart,
309    offset_minutes: i64,
310    requests: &[PipelineRequest],
311    natal_options: &NatalOptions,
312) -> Result<RenderModel, EngineError> {
313    #[cfg(feature = "eternal-bridge")]
314    {
315        bridge::compose(chart, offset_minutes, requests, natal_options)
316    }
317    #[cfg(not(feature = "eternal-bridge"))]
318    {
319        let _ = (offset_minutes, requests, natal_options);
320        Ok(compute_mock(chart))
321    }
322}
323
324/// Atajo: natal sin overlays. Equivalente a `compose(chart, 0, &[])`.
325pub fn compute(chart: &Chart) -> Result<RenderModel, EngineError> {
326    compose(chart, 0, &[])
327}
328
329/// Atajo: natal con time-scrubbing pero sin overlays.
330pub fn compute_at_offset(chart: &Chart, offset_minutes: i64) -> Result<RenderModel, EngineError> {
331    compose(chart, offset_minutes, &[])
332}
333
334/// Atajo: natal + overlay de tránsitos al instante actual.
335pub fn compute_with_transits_at_now(
336    chart: &Chart,
337    offset_minutes: i64,
338) -> Result<RenderModel, EngineError> {
339    compose(chart, offset_minutes, &[PipelineRequest::Transit])
340}
341
342/// Stub determinista — útil para tests + para la UI sin eternal.
343pub fn compute_mock(chart: &Chart) -> RenderModel {
344    use std::time::Instant;
345    let t0 = Instant::now();
346
347    let sign_dial = Layer {
348        module_id: "natal".into(),
349        kind: LayerKind::SignDial,
350        ring: 1.0,
351        z: 0,
352        geometry: Geometry::Ring {
353            cusps_deg: (0..12).map(|i| (i as f32) * 30.0).collect(),
354        },
355        glyphs: (0..12)
356            .map(|i| Glyph {
357                deg: (i as f32) * 30.0 + 15.0,
358                symbol: ZODIAC_GLYPHS[i].into(),
359                annotation: None,
360                retrograde: false,
361                house: None,
362            dignity_marker: None,
363            })
364            .collect(),
365    };
366
367    RenderModel {
368        chart_id: chart.id,
369        chart_kind: chart.kind,
370        title: chart.label.clone(),
371        subtitle: chart.birth_data.birthplace_label.clone(),
372        compute_ms: t0.elapsed().as_millis() as u64,
373        ascendant_deg: 0.0,
374        midheaven_deg: 270.0,
375        descendant_deg: 180.0,
376        imum_coeli_deg: 90.0,
377        layers: vec![sign_dial],
378        overlays: Vec::new(),
379        aspect_summary: Vec::new(),
380    }
381}
382
383const ZODIAC_GLYPHS: [&str; 12] = [
384    "aries",
385    "taurus",
386    "gemini",
387    "cancer",
388    "leo",
389    "virgo",
390    "libra",
391    "scorpio",
392    "sagittarius",
393    "capricorn",
394    "aquarius",
395    "pisces",
396];
397
398// =====================================================================
399// Tests
400// =====================================================================
401
402#[cfg(test)]
403mod tests {
404    use super::*;
405    use tahuantinsuyu_model::{
406        Chart, ChartKind, ContactId, StoredBirthData, StoredChartConfig,
407    };
408
409    fn sample_chart() -> Chart {
410        Chart {
411            id: ChartId::new(),
412            contact_id: ContactId::new(),
413            kind: ChartKind::Natal,
414            label: "test".into(),
415            birth_data: StoredBirthData {
416                year: 1987,
417                month: 3,
418                day: 14,
419                hour: 5,
420                minute: 22,
421                second: 0.0,
422                tz_offset_minutes: -240,
423                latitude_deg: 10.4806,
424                longitude_deg: -66.9036,
425                altitude_m: 900.0,
426                time_certainty: Default::default(),
427                subject_name: None,
428                birthplace_label: None,
429            },
430            config: StoredChartConfig::default(),
431            related_chart_id: None,
432            created_at_ms: 0,
433        }
434    }
435
436    #[test]
437    fn mock_emits_sign_dial() {
438        let model = compute_mock(&sample_chart());
439        assert_eq!(model.layers.len(), 1);
440        assert!(matches!(model.layers[0].kind, LayerKind::SignDial));
441        assert_eq!(model.layers[0].glyphs.len(), 12);
442    }
443
444    #[cfg(feature = "eternal-bridge")]
445    #[test]
446    fn real_compute_natal_demo() {
447        let model = compute(&sample_chart()).expect("compute con eternal");
448        assert!(model.layers.iter().any(|l| matches!(l.kind, LayerKind::SignDial)));
449        assert!(model.layers.iter().any(|l| matches!(l.kind, LayerKind::Houses)));
450        assert!(model.layers.iter().any(|l| matches!(l.kind, LayerKind::Bodies)));
451        // El Asc debe ser un grado válido.
452        assert!(model.ascendant_deg.is_finite());
453        assert!((0.0..360.0).contains(&model.ascendant_deg));
454    }
455}