tawasuyu/brahman

1//! `MetaBackend` trait — la frontera entre el widget metainterfaz
2//! (yahweh) y la implementación concreta de persistencia/ejecución
3//! (nakui-core, Surreal, mocks para tests).
4//!
5//! El widget consume este trait; el binario lo implementa con su
6//! stack particular. Esto es lo que hace que el widget sea reusable.
7//!
8//! Convenciones documentadas en el doc del trait abajo.
9
10use std::collections::BTreeMap;
11
12use serde_json::Value;
13use uuid::Uuid;
14
15/// Resultado uniforme de una operación de escritura del backend.
16///
17/// La UI lo usa para componer el toast: `id` para mostrar el
18/// short_uuid, `changed` para diferenciar "actualizado X (3 campos)"
19/// vs "sin cambios", `post_status` para concatenar mensajes
20/// emitidos por hooks internos del backend (ej. "auto-compact:
21/// snapshot @ seq 49") sin que la UI tenga que conocer el detalle.
22#[derive(Debug, Clone, Default, PartialEq, Eq)]
23pub struct WriteOutcome {
24    /// Id del record afectado. `Some` para seed/update/delete;
25    /// `None` para morphism cuando afecta múltiples records.
26    pub id: Option<Uuid>,
27    /// Cantidad de cambios efectivos. `0` = no-op (edit que no
28    /// modificó ningún campo, etc.).
29    pub changed: usize,
30    /// Mensaje de status opcional para concatenar al toast del op
31    /// original con el separator estándar.
32    pub post_status: Option<String>,
33}
34
35impl WriteOutcome {
36    /// Constructor para no-op writes (edits sin cambios).
37    pub fn no_change(id: Uuid) -> Self {
38        Self {
39            id: Some(id),
40            changed: 0,
41            post_status: None,
42        }
43    }
44}
45
46/// Backend que un widget de metainterfaz usa para leer y mutar
47/// records. Decoupla el widget (yahweh) de la implementación
48/// concreta (nakui-core, Surreal, mock para tests).
49///
50/// # Convención sobre ids
51///
52/// `Uuid` canónico. Backends que internamente usan otros tipos
53/// deben mapear via Uuid (hash determinista, wrapper, lo que sirva).
54/// Esto evita generic associated types que complicarían el dispatch
55/// en `cx.listener` de GPUI.
56///
57/// # Convención sobre validación
58///
59/// El backend ES la fuente de verdad sobre invariantes (KCL/Nickel
60/// post-checks, conservación, etc.). El widget pre-valida shape
61/// (yahweh-meta-runtime: `parse_field_value`, `validate_entity_refs`)
62/// pero el backend puede rebotar con `Err(...)` si su validación
63/// adicional falla — el widget muestra el error al usuario.
64///
65/// # Convención sobre threading
66///
67/// `'static` (no `Send + Sync`): el widget vive en `Entity<MetaApp<B>>`
68/// que requiere `'static`, pero los handlers son single-threaded en
69/// el main UI thread de GPUI. Si en el futuro un backend necesita
70/// `cx.spawn`, agregamos los marker traits.
71///
72/// # Convención sobre delta computation
73///
74/// El widget pre-computa `set` y `clear` con
75/// [`crate::delta::compute_field_delta`] +
76/// [`crate::delta::compute_clear_fields`] *antes* de llamar a
77/// [`MetaBackend::update`]. El backend no recomputa: si recibe ambos
78/// vacíos devuelve `changed = 0` sin escribir nada. Esto evita
79/// double-roundtrip al store por el mismo dato.
80pub trait MetaBackend: 'static {
81    /// Snapshot ordenado de records de una entity.
82    /// Orden estable (lexicográfico por id) para UI determinista.
83    /// Vacío si no hay records.
84    fn list_records(&self, entity: &str) -> Vec<(Uuid, Value)>;
85
86    /// Lee un record por id. `None` si no existe.
87    fn load_record(&self, entity: &str, id: Uuid) -> Option<Value>;
88
89    /// Crea un record nuevo. El backend asigna el `Uuid`
90    /// (devuelve en `WriteOutcome.id`). `changed = 1` siempre.
91    fn seed(
92        &mut self,
93        entity: &str,
94        data: serde_json::Map<String, Value>,
95    ) -> Result<WriteOutcome, String>;
96
97    /// Edita un record existente. Aplica `set` (overrides) y
98    /// `clear` (key removal). `changed = set.len() + clear.len()`.
99    /// Si ambos están vacíos (no-op edit), devuelve
100    /// `WriteOutcome::no_change(id)` sin error y sin escribir al log.
101    fn update(
102        &mut self,
103        entity: &str,
104        id: Uuid,
105        set: serde_json::Map<String, Value>,
106        clear: Vec<String>,
107    ) -> Result<WriteOutcome, String>;
108
109    /// Borra un record. `changed = 1` si existía, error si no.
110    fn delete(&mut self, entity: &str, id: Uuid) -> Result<WriteOutcome, String>;
111
112    /// Ejecuta un morphism declarado por un módulo. El backend
113    /// resuelve la implementación, valida, computa ops, las aplica.
114    /// `changed = N ops aplicadas`.
115    ///
116    /// `module_id` ubica al módulo (el trait no asume estructura del
117    /// manifest — el backend lo resuelve internamente).
118    fn morphism(
119        &mut self,
120        module_id: &str,
121        name: &str,
122        inputs: BTreeMap<String, Uuid>,
123        params: Value,
124    ) -> Result<WriteOutcome, String>;
125}
126
127#[cfg(test)]
128mod tests {
129    //! Tests del trait via [`crate::testing::MockBackend`]. Verifican
130    //! el contrato genérico (object-safety, semantica de seed/update/
131    //! delete) sin atar a un backend concreto. Los tests del mock en
132    //! sí (constructores, with_morphism, etc.) viven en
133    //! `crate::testing::tests`.
134
135    use super::*;
136    use crate::testing::MockBackend;
137    use serde_json::json;
138
139    fn map_of(items: &[(&str, Value)]) -> serde_json::Map<String, Value> {
140        items.iter().map(|(k, v)| (k.to_string(), v.clone())).collect()
141    }
142
143    #[test]
144    fn seed_then_load_round_trip() {
145        let mut b = MockBackend::new();
146        let out = b
147            .seed("Customer", map_of(&[("name", json!("Acme"))]))
148            .unwrap();
149        let id = out.id.expect("seed devuelve id");
150        assert_eq!(out.changed, 1);
151        assert!(out.post_status.is_none());
152
153        let rec = b.load_record("Customer", id).unwrap();
154        assert_eq!(rec.get("name"), Some(&json!("Acme")));
155    }
156
157    #[test]
158    fn list_records_filters_by_entity_and_orders_stably() {
159        let mut b = MockBackend::new();
160        let _ = b.seed("A", map_of(&[("k", json!(1))])).unwrap();
161        let _ = b.seed("B", map_of(&[("k", json!(2))])).unwrap();
162        let _ = b.seed("A", map_of(&[("k", json!(3))])).unwrap();
163
164        let a = b.list_records("A");
165        assert_eq!(a.len(), 2);
166        let b_only = b.list_records("B");
167        assert_eq!(b_only.len(), 1);
168        let none = b.list_records("Missing");
169        assert!(none.is_empty());
170
171        // Orden estable: re-llamadas devuelven mismo orden.
172        let a_again = b.list_records("A");
173        assert_eq!(
174            a.iter().map(|(id, _)| *id).collect::<Vec<_>>(),
175            a_again.iter().map(|(id, _)| *id).collect::<Vec<_>>(),
176        );
177    }
178
179    #[test]
180    fn update_with_set_changes_field() {
181        let mut b = MockBackend::new();
182        let id = b
183            .seed("Customer", map_of(&[("name", json!("Acme")), ("notes", json!("x"))]))
184            .unwrap()
185            .id
186            .unwrap();
187
188        let out = b
189            .update(
190                "Customer",
191                id,
192                map_of(&[("name", json!("Acme S.A."))]),
193                vec![],
194            )
195            .unwrap();
196        assert_eq!(out.changed, 1);
197        assert_eq!(out.id, Some(id));
198
199        let rec = b.load_record("Customer", id).unwrap();
200        assert_eq!(rec.get("name"), Some(&json!("Acme S.A.")));
201        assert_eq!(rec.get("notes"), Some(&json!("x")), "notes intacto");
202    }
203
204    #[test]
205    fn update_with_clear_removes_key() {
206        let mut b = MockBackend::new();
207        let id = b
208            .seed("Customer", map_of(&[("name", json!("Acme")), ("notes", json!("x"))]))
209            .unwrap()
210            .id
211            .unwrap();
212
213        let out = b
214            .update("Customer", id, serde_json::Map::new(), vec!["notes".into()])
215            .unwrap();
216        assert_eq!(out.changed, 1);
217
218        let rec = b.load_record("Customer", id).unwrap();
219        assert_eq!(rec.get("name"), Some(&json!("Acme")));
220        assert!(rec.get("notes").is_none(), "notes debería estar borrado");
221    }
222
223    #[test]
224    fn update_with_empty_set_and_clear_returns_no_change() {
225        let mut b = MockBackend::new();
226        let id = b
227            .seed("Customer", map_of(&[("name", json!("Acme"))]))
228            .unwrap()
229            .id
230            .unwrap();
231
232        let out = b
233            .update("Customer", id, serde_json::Map::new(), vec![])
234            .unwrap();
235        assert_eq!(out, WriteOutcome::no_change(id));
236    }
237
238    #[test]
239    fn update_on_missing_record_errors() {
240        let mut b = MockBackend::new();
241        let id = Uuid::new_v4();
242        let err = b
243            .update("Customer", id, map_of(&[("x", json!(1))]), vec![])
244            .unwrap_err();
245        assert!(err.contains("not found"));
246    }
247
248    #[test]
249    fn delete_removes_and_then_load_returns_none() {
250        let mut b = MockBackend::new();
251        let id = b
252            .seed("Customer", map_of(&[("name", json!("Acme"))]))
253            .unwrap()
254            .id
255            .unwrap();
256        let out = b.delete("Customer", id).unwrap();
257        assert_eq!(out.changed, 1);
258        assert_eq!(out.id, Some(id));
259        assert!(b.load_record("Customer", id).is_none());
260    }
261
262    #[test]
263    fn delete_on_missing_record_errors() {
264        let mut b = MockBackend::new();
265        let id = Uuid::new_v4();
266        assert!(b.delete("Customer", id).is_err());
267    }
268
269    /// Sanity: el trait acepta llamadas via `&mut dyn MetaBackend`
270    /// (object-safety). Esto permite que el widget tenga
271    /// `Box<dyn MetaBackend>` si el use case requiere borrado de
272    /// tipo (vs. el path normal con `MetaApp<B: MetaBackend>`).
273    #[test]
274    fn trait_is_object_safe() {
275        let mut b: Box<dyn MetaBackend> = Box::new(MockBackend::new());
276        let _ = b.seed("X", map_of(&[("k", json!(1))])).unwrap();
277        assert_eq!(b.list_records("X").len(), 1);
278    }
279}