Sincronización bidireccional con Obsidian — diseño propuesto

<!-- translations:start -->

English · 한국어 · 中文 · 日本語 · Русский · Français · Deutsch

<!-- translations:end -->

Estado: Entregado (Tier 1, v0.5.0). El lector de overlay, las zonas de agregación de user-notes, el modo watch y la limpieza de huérfanos descritos abajo están vivos tras tesserae vault sync. Esta página sirve a la vez de justificación de diseño y de guía de usuario. La federación multi-vault (Tier 3) sigue fuera de alcance.

La exportación a Obsidian solía ser estrictamente unidireccional: el grafo tipado en .tesserae/graph.json se proyecta al vault, y project compile sobrescribe los archivos proyectados. obsidian-sync añade la dirección opuesta — edita una descripción en Obsidian y sobrevive a la recompilación.

Este documento detalla cómo funciona eso sin volver incoherente el modelo de datos.

Cambio estratégico, dicho con claridad

El README actual desautoriza la edición en vivo:

Tesserae elige compilar-desde-la-fuente en lugar de la edición en vivo. Si quieres editar notas en una UI, usa Logseq u Obsidian.

La sincronización bidireccional cambia ese contrato para un subconjunto de campos. Vale la pena ser deliberado al respecto. El objetivo no es "Obsidian se convierte en el editor" — es "las ediciones del usuario en Obsidian no se destruyen silenciosamente al recompilar".

La idea central: overlays, no merges

En lugar de intentar fusionar dos copias divergentes del mismo nodo, trata el vault como una capa de diff sobre la proyección:

source markdown  ──extract──▶  base_graph
                                    +
                              vault_overrides     ◀── computed from vault
                                    ↓
                              final_graph  ──project──▶  vault (.md files)

vault_overrides.json vive en .tesserae/ y es calculado, no escrito a mano. En cada compilación, Tesserae recorre el vault, compara cada página proyectada con lo que la proyección anterior escribió, y registra cada cambio introducido por el usuario como una entrada del overlay. El grafo final es base_graph con los overlays aplicados. La siguiente proyección escribe el resultado de vuelta a disco.

Estable en el viaje de ida y vuelta. Recompilar el mismo vault sin cambios en el lado de la fuente no produce diffs.

Propiedad por campo

Cada campo de un nodo tiene un propietario. La propiedad decide qué pasa cuando la fuente y el vault no coinciden.

Casos de conflicto y comportamientos por defecto

Zona de agregación de user-notes

Cada página proyectada recibe una zona delimitada que el proyector nunca toca:

> [!quote] Paper
> Headline contribution and method sketch projected from the graph...

<!-- user-notes:start -->

Your notes here. Anything between the markers survives recompile forever.
Wikilinks here become `user_link` edges in the graph on the next pull.

<!-- user-notes:end -->

## Outgoing
- ...

Dos efectos prácticos:

1. Los usuarios pueden anotar cualquier página (p. ej. "ver capítulo 4 de mis notas") sin perderlo al reconstruir.
2. La pasada de pull escanea el bloque user-notes en busca de wikilinks y los expone como aristas user_link tipadas en la ontología, dándoles alcance en el grafo sin contaminar los tipos formales de aristas.

Transporte remoto — no-objetivo explícito

Tesserae no construye un servidor de sincronización, una capa de autenticación, un daemon de resolución de conflictos ni un vault alojado. "Bidireccional" aquí significa "la compilación lee del vault" — qué hace que el vault llegue a la máquina que ejecuta la compilación es problema del usuario, resuelto por herramientas que ya existen:

Los cinco son compatibles con el modelo de overlay porque Tesserae ve el vault como archivos-en-disco, no como un flujo de mutaciones.

Superficie de CLI

tesserae vault sync aplica las ediciones del vault sobre el grafo tipado y reproyecta:

# Aplicar el overlay una vez: trae ediciones de usuario, reproyecta al vault.
tesserae vault sync

# Inspecciona primero qué cambiaría. Escribe .tesserae/diverged-fields.md y
# NO aplica ni reproyecta.
tesserae vault sync --dry-run

# Apunta a un vault concreto para esta llamada (orden de resolución:
# --vault > config.obsidian.vault_path > .tesserae/obsidian_vault/).
tesserae vault sync --vault ~/Documents/tesserae-vault

# Hacer que esa ruta de vault sea el valor por defecto para futuros comandos.
tesserae vault sync --vault ~/Documents/tesserae-vault --persist-vault

# Watch de larga duración: reaplica el overlay cada vez que cambia el vault.
# Ctrl-C para detener; ajusta la cadencia con --poll-interval (por defecto 1.5 s).
tesserae vault sync --watch --poll-interval 1.5

# Elimina páginas proyectadas cuyo nodo fuente ya no existe (el proyector
# solo sobrescribe, nunca borra). Las páginas con user-notes se conservan
# salvo que pases también --force-prune-with-notes.
tesserae vault sync --prune-orphans
tesserae vault sync --prune-orphans --force-prune-with-notes

El comando slash /tesserae:obsidian-sync lo envuelve, y tesserae refresh (más la macro /tesserae:refresh) ejecuta el overlay como último paso de su cadena import → compile → sync.

Estado de entrega

No-objetivos (explícitamente)

• Un servidor de sincronización / auth / backend alojado.
• Edición colaborativa en tiempo real dentro de Obsidian (usa LiveSync si lo necesitas).
• Reescribir el extractor para hacer round-trip de cada campo — el markdown fuente sigue siendo canónico para todo lo que esté fuera de la tabla de overrides.
• Sincronización del sitio HTML estático (build-site sigue siendo solo proyección).

Decisiones resueltas

Estas eran las preguntas abiertas en el momento del diseño; la implementación entregada de Tier 1–2 las resolvió así:

1. Forma del lint report. Los campos divergentes aparecen como un archivo dedicado .tesserae/diverged-fields.md (escrito por --dry-run y en cada aplicación) para poder diffearlo en git, en lugar de como una sección de lint-report.md.
2. Tipo de nodo lápida. ¿Añadir Stub como un tipo real del esquema, o aprovechar OpenQuestion con un discriminador _kind: stub? Propuesta: tipo real, llamado Stub, oculto de los índices públicos.
3. Pull-on-compile por defecto. ¿Por defecto activado o desactivado? Propuesta: activado cuando existe un vault en la ruta configurada, con un prompt de confirmación único la primera vez que se activa para que los usuarios opten deliberadamente.
4. ¿Qué cuenta como "la proyección anterior" para el diff? ¿Snapshot guardado en .tesserae/vault_snapshot.json, o re-proyectar al vuelo en cada compilación? Propuesta: snapshot, escrito al final de cada compilación. Más barato y evita que el no-determinismo del extractor se filtre al overlay.
5. Proyección de vault multilingüe. La proyección actual es monolingüe (la de la fuente). ¿Deberían los overlays ser conscientes del idioma (p. ej. que una edición a description en un vault coreano se aplique solo a la proyección coreana)? Propuesta: fuera de alcance para v1; el vault es monolingüe coincidiendo con el idioma principal del proyecto.

Cómo aparece esto en obsidian.md

La guía de cara al usuario sigue centrada en "puedes leer y consultar el vault", y luego enlaza aquí para la historia del ida y vuelta con un resumen de una línea: "Edita campos en Obsidian, sobreviven a la recompilación. Ver obsidian-sync.md para el modelo completo."