Synchronisation bidirectionnelle Obsidian — conception proposée

<!-- translations:start -->

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

<!-- translations:end -->

Statut : Proposé (2026-05-17). Ce document est une spécification de conception, pas encore une fonctionnalité. Il décrit comment Tesserae pourrait permettre aux utilisateurs de modifier dans Obsidian les pages wiki projetées et faire en sorte que ces modifications survivent au prochain project compile. La mise en œuvre est conditionnée à l'adoption de cette conception.

Aujourd'hui, l'export Obsidian est strictement à sens unique : le graphe typé dans .tesserae/graph.json est projeté vers le vault, et project compile écrase les fichiers projetés. Les utilisateurs ont demandé l'inverse également — modifier une description dans Obsidian et la voir survivre à la recompilation.

Ce document précise comment cela fonctionnerait 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 (proposée)

# Pull-only sync (Tier 1a): overlay reader runs as part of compile by default.
tesserae project compile                  # always pulls vault overrides if vault exists

# Inspect what would change before letting compile apply
tesserae project obsidian-sync --dry-run

# Skip the pull for a single compile (recovery mode)
tesserae project compile --no-vault-pull

# Long-running watch (Tier 2)
tesserae project obsidian-sync --watch --vault ~/Documents/tesserae-vault

Phasage

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 ouvertes avant implémentation

Celles-ci ont des valeurs par défaut proposées, mais méritent une dernière revue avant que le code n'atterrisse :

1. Forme du lint report. Les champs divergents devraient-ils apparaître comme un fichier .tesserae/diverged-fields.md séparé, ou comme une nouvelle section dans le lint-report.md existant ? Proposé : fichier dédié pour qu'il puisse être diffé en git.
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 ». Une courte section « Synchronisation bidirectionnelle » à la fin renverra ici une fois l'implémentation livrée, 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. »

D'ici là, l'avertissement read-only existant dans obsidian.md reste en place — cette conception est une feuille de route, pas une fonctionnalité livrée.