Saltar a contenido

DDR-008 — Reflect cura el grafo y los Insights viven dentro de él

Versión: 0.1.0 | Fecha: 2026-09-24 | Estado: Aceptado

Contexto

engrama_reflect detecta patrones entre entidades y escribe nodos Insight para que una persona los revise. Tiene tres problemas.

  • Los Insights son huérfanos por construcción. Reflect crea cada Insight con merge_node y nunca lo enlaza con los nodos de los que habla. En un grafo en el que reflect se ejecuta con regularidad, los Insights son la mayoría de los nodos de grado 0. Inflan cualquier recuento de huérfanos, y no se puede llegar a ellos desde las entidades que describen.
  • Los detectores hacen ruido donde disparan y están ciegos donde importa.
  • shared_technology emite un Insight por cada par de entidades que comparten una tecnología (N² por tecnología), sin excluir nodos superseded ni archived. La cola de revisión se llena de Insights casi idénticos que acaban descartados a mano.
  • under_connected filtra con n.status <> 'archived', que en la lógica de tres valores de Cypher descarta todos los nodos que no tienen status. Además solo devuelve los 15 nodos más recientes, así que el backlog de nodos de grado 0 nunca aflora. El backend SQLite usa COALESCE y se comporta de forma distinta.
  • No hay ningún detector para los problemas que de verdad degradan el grafo: entidades duplicadas, hub stubs, tags sin arista, puentes archivados y conflictos de label.

Decisión

Reflect pasa a ser el curador del grafo. Sus detectores son correctos y agregados, encuentra problemas estructurales además de patrones de dominio, cada Insight queda enlazado a su evidencia, y un Insight de curación aprobado puede llevar la acción no destructiva que corrige el problema que señala. La fusión de nodos queda deliberadamente fuera de este DDR.

En concreto

  1. Corrección de los detectores.
  2. Un único helper live_filter(var), seguro frente a nulos (coalesce(n.status, 'active') NOT IN ['archived', 'superseded']), que usan todos los detectores en los dos backends.
  3. under_connected informa del recuento total más una muestra, en lugar de LIMIT 15.
  4. Un test de paridad ejecuta cada detector sobre SQLite y Neo4j con el mismo fixture.
  5. Agregación. shared_technology emite un Insight por tecnología con 3 o más usuarios vivos, con la lista de miembros, en lugar de uno por par. Cada detector tiene un presupuesto por ejecución, para que una sola ejecución no pueda inundar la cola.
  6. Detectores de curación.
  7. orphans: grado 0, sin contar los Insights de sistema (DDR-006, punto 7). Los Insights escritos a mano cuentan como nodos de dominio aquí y en el resto de detectores, que hoy ignoran :Insight por completo.
  8. hub_stubs: stub con grado ≥ 3.
  9. merge_candidates: pares del resolvedor por encima del umbral (DDR-006). Solo informa: resolver un candidato sigue siendo una decisión humana.
  10. tag_without_edge: tag que se resuelve a un ancla no enlazada.
  11. archived_bridges: nodos archivados cuyos vecinos están vivos.
  12. label_conflicts.
  13. archive_candidates: recencia al leer baja, grado bajo y sin vecinos vivos (DDR-007).
  14. Los Insights quedan enlazados. Cada Insight recibe (:Insight)-[:ABOUT]->(n) por cada entidad que devolvió su detector. ABOUT es un tipo de relación del núcleo, independiente del perfil. Las métricas de huérfanos excluyen los Insights de sistema por definición, y engrama_context sobre una entidad muestra los Insights que hablan de ella.
  15. Aprobaciones con acción. Un Insight de curación guarda una proposed_action legible por máquina: link, enrich o archive. Ninguna borra datos (archive es reversible mediante reactivación). engrama_approve_insight(..., apply=true) la ejecuta con las mismas tools que usaría una persona, dentro del scope de quien llama. Sin apply, aprobar se comporta como hoy.
  16. Ciclo de vida de los Insights. Un Insight regenerado refresca su body, su confianza y sus aristas ABOUT, salvo que una persona ya lo haya juzgado (DDR-007, punto 5). La cola de revisión (engrama_surface_insights, engrama_approve_insight) solo maneja Insights de sistema, así que los escritos a mano nunca aparecen como pendientes.

Consecuencias

  • Positivas:
  • Los recuentos de huérfanos vuelven a medir el grafo de dominio.
  • Revisar Insights se convierte en un ciclo de curación que corrige los problemas que señala.
  • El ruido del detector de tecnologías baja un orden de magnitud.
  • Negativas:
  • Los duplicados se señalan pero no se resuelven: mientras no exista una operación de fusión, corregir uno implica reenlazar aristas a mano.
  • Más detectores significa un reflect más lento. Reflect se ejecuta bajo demanda, y cada detector mantiene un presupuesto.
  • Neutras:
  • Los Insights existentes siguen funcionando. Reciben sus aristas ABOUT la próxima vez que reflect los regenere.

Seguimientos abiertos (no bloqueantes)

  • Una operación de fusión (engrama_merge) que integre el nodo B en el nodo A: redirige las aristas, une las propiedades, conserva la clave de B como alias y registra su engrama_id. Es destructiva, así que tendrá su propio DDR, que cubra deshacer, auditoría y notas del vault, antes de implementarse.
  • Que un EntityDecider (DDR-006) puntúe los candidatos a fusión en lugar de un umbral fijo.
  • Un informe engrama health (solo lectura y con scope) que exponga las mismas métricas que los detectores de curación, para paneles y arneses de evaluación.

Referencias

  • DDR-006: resolvedor de entidades, ciclo de vida de los stubs e Insights de sistema frente a escritos a mano.
  • DDR-007: recencia al leer y archivado explícito.