Sync bidirectionnelle Obsidian — conception proposée

<!-- translations:start -->

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

<!-- translations:end -->

Statut : livré (Tier 1, v0.5.0). Le lecteur d’overlay, les zones d’ajout de notes utilisateur, le mode watch et l’élagage des orphelins décrits ci-dessous sont actifs derrière tesserae vault sync. Cette page sert à la fois 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 auparavant strictement à sens unique : le graphe typé de .tesserae/graph.json se projette vers le vault, et project compile écrase les fichiers projetés. obsidian-sync ajoute la direction opposée — éditez une description dans Obsidian, et elle survit à la recompilation.

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

Le virage stratégique, énoncé clairement

Le README actuel décline l’édition en direct :

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

La sync bidirectionnelle change ce contrat pour un sous-ensemble de champs. Cela mérite d’être délibéré. Le but n’est pas « Obsidian devient l’éditeur » — c’est « les éditions Obsidian de l’utilisateur ne sont pas silencieusement détruites à la recompilation ».

L’idée centrale : des overlays, pas des merges

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

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

vault_overrides.json vit dans .tesserae/ et est calculé, pas écrit à la main. À chaque compilation, Tesserae parcourt le vault, compare chaque page projetée à ce que la projection précédente a écrit, et enregistre chaque changement introduit par l’utilisateur comme une entrée d’overlay. Le graphe final est base_graph avec les overlays appliqués. La projection suivante réécrit le résultat sur disque.

Stable en aller-retour. 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écide de ce qui se passe quand la source et le vault sont en désaccord.

Cas de conflit et défauts

Zone d’ajout de notes utilisateur

Chaque page projetée reçoit une zone clôturé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 (p. ex. « voir le chapitre 4 de mes notes ») sans la perdre à la reconstruction.
2. La passe de pull scanne le bloc de notes utilisateur à la recherche de wikilinks et les expose comme des arêtes user_link typées par l’ontologie, leur donnant l’atteignabilité du graphe sans polluer les types d’arêtes formels.

Transport distant — non-objectif explicite

Tesserae ne construit pas de serveur de sync, de couche d’auth, de daemon de résolution de conflits, ni de vault hébergé. « Bidirectionnel » signifie ici « la compilation lit depuis le vault » — comment le vault arrive à 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 d’overlay 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 re-projette :

# Apply the overlay once: pull user edits, re-project to the vault.
tesserae vault sync

# Inspect what would change first. Writes .tesserae/diverged-fields.md and
# does NOT apply or re-project.
tesserae vault sync --dry-run

# Point at a specific vault for this call (resolution order:
# --vault > config.obsidian.vault_path > .tesserae/obsidian_vault/).
tesserae vault sync --vault ~/Documents/tesserae-vault

# Make that vault path the default for future commands.
tesserae vault sync --vault ~/Documents/tesserae-vault --persist-vault

# Long-running watch: re-apply the overlay every time the vault changes.
# Ctrl-C to stop; tune the poll cadence with --interval (default 1.5s).
tesserae vault sync --watch --interval 1.5

# Delete projected pages whose source node no longer exists (the projector
# only overwrites, never deletes). Pages with user-notes are kept unless you
# also pass --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’enrobe, et tesserae refresh (plus la macro /tesserae:refresh) exécute l’overlay comme dernière étape de sa chaîne import → compile → sync.

Statut de livraison

Non-objectifs (explicitement)

• Un serveur de sync / auth / backend hébergé.
• L’édition collaborative en temps réel dans Obsidian (utilisez LiveSync si vous en avez besoin).
• Réécrire l’extracteur pour faire l’aller-retour de chaque champ — le markdown source reste canonique pour tout ce qui est hors de la table d’override.
• La sync du site HTML statique (build-site reste projection seulement).

Décisions tranchées

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

1. Forme du rapport de lint. Les champs divergents apparaissent dans un fichier dédié .tesserae/diverged-fields.md (écrit par --dry-run et à chaque application) pour pouvoir être diffé dans git, plutôt que comme une section de lint-report.md.
2. Type de nœud pierre tombale. Ajouter Stub comme un vrai type de schéma, ou s’appuyer sur OpenQuestion avec un discriminateur _kind: stub ? Proposé : un vrai type, nommé Stub, caché des index publics.
3. Pull-à-la-compilation par défaut. ON ou OFF par défaut ? Proposé : ON quand un vault existe au chemin configuré, avec une invite de confirmation unique à la première activation pour que les utilisateurs optent délibérément.
4. Qu’est-ce qui compte comme « la projection précédente » pour le diff ? Snapshot stocké dans .tesserae/vault_snapshot.json, ou re-projeter à la volée à chaque compilation ? Proposé : snapshot, écrit à la fin de chaque compilation. Moins cher et évite que le non-déterminisme de l’extracteur ne fuie dans l’overlay.
5. Projection de vault multilingue. La projection actuelle est monolingue (la source). Les overlays devraient-ils être conscients de la locale (p. ex. une édition 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, aligné sur la langue principale du projet.

Comment cela apparaît dans obsidian.md

Le guide côté utilisateur reste centré sur « vous pouvez lire et interroger le vault », puis lie ici pour l’histoire de l’aller-retour avec un résumé d’une ligne : « Éditez des champs dans Obsidian, ils survivent à la recompilation. Voir obsidian-sync.md pour le modèle complet. »