Synchronisation bidirectionnelle Obsidian — conception proposée

<!-- translations:start -->

English · 한국어 · 中文 · 日本語 · Русский · Español · Deutsch

<!-- translations:end -->

Statut : Livré (Tier 1, v0.5.0). Le lecteur de surcouches, les zones d'ajout user-notes, le mode watch et le nettoyage des orphelins décrits ci-dessous sont actifs derrière tesserae vault sync. Cette page fait à la fois office de justification de conception et de guide utilisateur. La fédération multi-vaults (Tier 3) reste hors périmètre.

L'export Obsidian était autrefois strictement à sens unique : le graphe typé dans .tesserae/graph.json est projeté vers le vault, et project compile écrase les fichiers projetés. obsidian-sync ajoute le sens inverse — modifiez une description dans Obsidian, et elle survit à la recompilation.

Ce document précise comment cela fonctionne sans rendre incohérent le modèle de données.

Changement stratégique, énoncé clairement

Le README actuel décline toute responsabilité concernant l'édition en direct :

Tesserae choisit la compilation depuis la source plutôt que l'édition en direct. Si vous voulez éditer des notes dans une UI, utilisez Logseq ou Obsidian.

La synchronisation bidirectionnelle modifie ce contrat pour un sous-ensemble de champs. Cela mérite d'être délibéré. L'objectif n'est pas qu'« Obsidian devienne l'éditeur » — c'est que « les modifications de l'utilisateur dans Obsidian ne soient pas silencieusement détruites lors de la recompilation ».

L'idée centrale : des surcouches, pas des fusions

Plutôt que d'essayer de fusionner deux copies divergentes du même nœud, traitez le vault comme une couche de diff par-dessus la projection :

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

vault_overrides.json réside dans .tesserae/ et est calculé, pas rédigé manuellement. À chaque compilation, Tesserae parcourt le vault, compare chaque page projetée à ce que la projection précédente avait écrit, et enregistre chaque modification introduite par l'utilisateur sous forme d'entrée de surcouche. Le graphe final est base_graph avec les surcouches appliquées. La projection suivante réécrit le résultat sur disque.

Round-trip stable. Recompiler le même vault sans changements côté source ne produit aucun diff.

Propriété par champ

Chaque champ d'un nœud a un propriétaire. La propriété détermine ce qui se passe lorsque la source et le vault divergent.

Cas de conflit et valeurs par défaut

Zone d'ajout user-notes

Chaque page projetée se voit dotée d'une zone délimitée que le projecteur ne touche jamais :

> [!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
- ...

Deux effets pratiques :

1. Les utilisateurs peuvent annoter n'importe quelle page (par ex. « voir le chapitre 4 de mes notes ») sans rien perdre lors d'une reconstruction.
2. La passe de pull scanne le bloc user-notes à la recherche de wikilinks et les expose comme arêtes typées ontologiquement user_link, leur donnant une accessibilité dans le graphe sans polluer les types d'arêtes formels.

Transport distant — non-objectif explicite

Tesserae ne construit pas de serveur de synchronisation, de couche d'authentification, de démon de résolution de conflits, ni de vault hébergé. « Bidirectionnel » signifie ici « la compilation lit depuis le vault » — ce qui amène le vault jusqu'à la machine qui compile est le problème de l'utilisateur, résolu par des outils qui existent déjà :

Les cinq sont compatibles avec le modèle de surcouches parce que Tesserae voit le vault comme des fichiers sur disque, pas comme un flux de mutations.

Surface CLI

tesserae vault sync applique les éditions du vault sur le graphe typé et reprojette :

# Appliquer la surcouche une fois : récupère les éditions utilisateur, reprojette vers le vault.
tesserae vault sync

# Inspecte d'abord ce qui changerait. Écrit .tesserae/diverged-fields.md et
# N'applique PAS et ne reprojette pas.
tesserae vault sync --dry-run

# Cibler un vault précis pour cet appel (ordre de résolution :
# --vault > config.obsidian.vault_path > .tesserae/obsidian_vault/).
tesserae vault sync --vault ~/Documents/tesserae-vault

# Faire de ce chemin de vault la valeur par défaut des futures commandes.
tesserae vault sync --vault ~/Documents/tesserae-vault --persist-vault

# Watch long-running : réapplique la surcouche à chaque changement du vault.
# Ctrl-C pour arrêter ; --poll-interval règle la cadence (par défaut 1,5 s).
tesserae vault sync --watch --poll-interval 1.5

# Supprime les pages projetées dont le nœud source n'existe plus (le projecteur
# ne fait qu'écraser, ne supprime jamais). Les pages avec user-notes sont
# conservées sauf si vous passez aussi --force-prune-with-notes.
tesserae vault sync --prune-orphans
tesserae vault sync --prune-orphans --force-prune-with-notes

La commande slash /tesserae:obsidian-sync l'enveloppe, et tesserae refresh (plus la macro /tesserae:refresh) exécute la surcouche comme dernière étape de sa chaîne import → compile → sync.

État de livraison

Non-objectifs (explicitement)

• Un serveur de sync / une authentification / un backend hébergé.
• L'édition collaborative en temps réel à l'intérieur d'Obsidian (utilisez LiveSync si vous en avez besoin).
• Réécrire l'extracteur pour faire un round-trip de chaque champ — la source markdown reste canonique pour tout ce qui se trouve en dehors de la table de surcharges.
• La synchronisation du site HTML statique (build-site reste exclusivement de la projection).

Décisions tranchées

C'étaient les questions ouvertes au moment de la conception ; l'implémentation livrée de Tier 1–2 les a tranchées ainsi :

1. Forme du lint report. Les champs divergents apparaissent comme un fichier dédié .tesserae/diverged-fields.md (écrit par --dry-run et à chaque application) afin de pouvoir être diffé en git, plutôt que comme une section de lint-report.md.
2. Type de nœud tombstone. Ajouter Stub comme véritable type du schéma, ou se greffer sur OpenQuestion avec un discriminant _kind: stub ? Proposé : type réel, nommé Stub, masqué des index publics.
3. Pull-on-compile par défaut. Activé par défaut ou désactivé par défaut ? Proposé : activé lorsqu'un vault existe au chemin configuré, avec une invite de confirmation unique la première fois qu'il s'active, afin que les utilisateurs y consentent délibérément.
4. Ce qui compte comme « la projection précédente » pour faire le diff. Un snapshot stocké dans .tesserae/vault_snapshot.json, ou re-projeter à la volée à chaque compilation ? Proposé : snapshot, écrit à la fin de chaque compilation. Moins coûteux et évite que le non-déterminisme de l'extracteur ne fuite dans la surcouche.
5. Projection vault multilingue. La projection actuelle est monolingue (la source). Les surcouches devraient-elles être locale-aware (par ex. une modification de description dans un vault coréen ne s'applique qu'à la projection coréenne) ? Proposé : hors périmètre pour la v1 ; le vault est monolingue, correspondant à la langue principale du projet.

Comment cela apparaît dans obsidian.md

Le guide destiné aux utilisateurs reste centré sur « vous pouvez lire et interroger le vault », puis renvoie ici pour l'histoire de l'aller-retour avec un résumé d'une ligne : « Modifiez des champs dans Obsidian, ils survivent à la recompilation. Voir obsidian-sync.md pour le modèle complet. »