DDR-002 — Sincronización bidireccional y portabilidad del vault

Versión: 0.1.0 | Fecha: 2026-04-12 | Estado: Aceptado

Contexto

DDR-001 estableció un sistema de clasificación facetada donde las relaciones (INSTANCE_OF, COMPOSED_OF, IN_DOMAIN, etc.) son el mecanismo principal para el descubrimiento entre dominios. Estas relaciones vivían exclusivamente en Neo4j. El vault de Obsidian almacenaba solo las propiedades de los nodos en su frontmatter.

Esto creaba una asimetría: si se perdía Neo4j, engrama_sync_vault podía recrear los nodos desde el vault, pero todas las relaciones facetadas desaparecían — la parte más valiosa del grafo. El vault era portable (archivos .md planos en cualquier servicio de sincronización); el grafo no lo era.

Decisión

Serializar todas las relaciones en el frontmatter YAML de cada nota. Tanto el vault como el grafo son fuentes de verdad co-iguales. La sincronización bidireccional las mantiene coherentes.

Formato del frontmatter

---
engrama_id: 550e8400-e29b-41d4-a716-446655440000
type: Problem
name: implicit-type-coercion-bug
status: resolved
relations:
  INSTANCE_OF: [type-safety-violation]
  COMPOSED_OF: [TypeScript]
  SOLVED_BY: [enable-strict-null-checks]
  BELONGS_TO: [EOElite]
  IN_DOMAIN: [web-development]
---

Contrato de sincronización

Dirección	Disparador	Qué sucede
Grafo → Vault	El modelo crea/elimina una relación vía engrama_relate	La relación se escribe/elimina del frontmatter de la nota origen
Vault → Grafo	engrama_sync_vault (modo normal)	Todas las relaciones del frontmatter se hacen MERGE en Neo4j
Grafo → Vault	engrama_sync_vault --from-graph	Todas las notas se regeneran con el frontmatter completo desde el grafo

Reglas de resolución

Escenario	Resolución
La relación existe en ambos	Sin acción (MERGE idempotente)
Relación en el vault, no en el grafo	Crear en el grafo (el vault gana — portabilidad)
Relación en el grafo, no en el vault	Escribir en el frontmatter del vault (el grafo gana — operacional)
Conflicto (destinos diferentes)	Marcar para revisión del usuario, no resolver automáticamente

Valores de las relaciones

• Los valores en el mapa relations son arrays de nombres (o títulos) de nodos destino, no engrama_ids.
• Los nombres son legibles por humanos y portables. Los IDs son internos.
• Si un nodo destino no existe durante la sincronización, crear un nodo stub (solo nombre, status: "stub").

Consecuencias

Positivas

• Portabilidad total: vault en cualquier servicio de sincronización en la nube → máquina nueva → engrama_sync_vault → grafo completo.
• Copia de seguridad real: el vault ES la copia de seguridad. No se necesita un proceso de exportación/importación separado.
• Relaciones legibles por humanos: cualquiera puede leer el frontmatter y entender la clasificación de la entidad.
• Compatible con Git: las relaciones como diffs de YAML son revisables y se pueden hacer merge.

Negativas

• Tamaño del frontmatter: los nodos muy conectados producen un frontmatter extenso. Aceptable — YAML maneja bien los arrays y Obsidian no tiene problemas con frontmatter largo.
• Coste de escritura dual: cada escritura de relación son dos operaciones (grafo + vault). Aceptable — la escritura en el vault es una edición de archivo pequeña.
• Complejidad de la sincronización: la sincronización bidireccional es intrínsecamente más compleja que la unidireccional. Mitigado por la semántica MERGE (idempotente) y la señalización de conflictos (sin sobreescrituras silenciosas).

Sustituye

Este DDR modifica la Regla 9 del system prompt. Anterior: "El vault es derivado, el grafo es la verdad." Nuevo: "Sincronización bidireccional — al crear una relación en el grafo, SIEMPRE escribidla también en el frontmatter de la nota."