Bidirektionale Obsidian-Synchronisation — vorgeschlagener Entwurf

<!-- translations:start -->

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

<!-- translations:end -->

Status: Ausgeliefert (Tier 1, v0.5.0). Der unten beschriebene Overlay-Reader, die User-Notes-Append-Zonen, der Watch-Modus und das Aufräumen verwaister Seiten sind hinter tesserae vault sync live. Diese Seite dient zugleich als Design-Begründung und als Nutzerhandbuch. Multi-Vault-Föderation (Tier 3) bleibt außerhalb des Umfangs.

Der Obsidian-Export war früher strikt einseitig: Der typisierte Graph in .tesserae/graph.json projiziert in den Vault, und project compile überschreibt projizierte Dateien. obsidian-sync ergänzt die Gegenrichtung — bearbeite eine Beschreibung in Obsidian, und sie überlebt das Recompile.

Dieses Dokument legt dar, wie das funktioniert, ohne das Datenmodell inkohärent zu machen.

Strategische Verschiebung, klar benannt

Die aktuelle README weist Live-Editing explizit zurück:

Tesserae entscheidet sich für Compile-from-Source statt Live-Editing. Wer Notizen in einer UI bearbeiten will, nimmt Logseq oder Obsidian.

Bidirektionale Synchronisation ändert diesen Vertrag für eine Teilmenge der Felder. Das verdient bewusste Auseinandersetzung. Das Ziel ist nicht „Obsidian wird zum Editor" — sondern „die Obsidian-Edits des Nutzers werden beim Recompile nicht stillschweigend zerstört".

Die Grundidee: Overlays statt Merges

Statt zu versuchen, zwei auseinanderdriftende Kopien desselben Nodes zu mergen, wird der Vault als Diff-Layer über der Projektion behandelt:

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

vault_overrides.json liegt in .tesserae/ und wird berechnet, nicht von Hand verfasst. Bei jedem Compile durchläuft Tesserae den Vault, vergleicht jede projizierte Seite mit dem, was die vorherige Projektion geschrieben hat, und erfasst jede vom Nutzer eingebrachte Änderung als Overlay-Eintrag. Der finale Graph ist base_graph mit angewandten Overlays. Die nächste Projektion schreibt das Ergebnis zurück auf die Platte.

Round-Trip-stabil. Ein erneutes Compile desselben Vaults ohne quellseitige Änderungen erzeugt keine Diffs.

Eigentümerschaft pro Feld

Jedes Feld eines Nodes hat einen Eigentümer. Die Eigentümerschaft entscheidet, was passiert, wenn Quelle und Vault nicht übereinstimmen.

Konfliktfälle und Defaults

User-Notes-Append-Zone

Jede projizierte Seite bekommt eine eingezäunte Zone, die der Projector niemals anfasst:

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

Zwei praktische Effekte:

1. Nutzer können jede Seite annotieren (z. B. „siehe Kapitel 4 meiner Notizen"), ohne sie beim Rebuild zu verlieren.
2. Der Pull-Durchlauf scannt den User-Notes-Block nach Wikilinks und exponiert sie als ontologisch typisierte user_link-Edges, was ihnen Graph-Erreichbarkeit verschafft, ohne die formalen Edge-Typen zu verschmutzen.

Remote-Transport — explizites Nicht-Ziel

Tesserae baut keinen Sync-Server, keinen Auth-Layer, keinen Conflict-Resolution-Daemon und keinen gehosteten Vault. „Bidirektional" bedeutet hier „Compile liest aus dem Vault" — wie der Vault auf die Compile-Maschine kommt, ist Sache des Nutzers, gelöst mit Tools, die es längst gibt:

Alle fünf sind mit dem Overlay-Modell kompatibel, weil Tesserae den Vault als Dateien-auf-Platte sieht, nicht als Strom von Mutationen.

CLI-Oberfläche

tesserae vault sync wendet Vault-Edits auf den typisierten Graphen an und projiziert neu:

# Overlay einmal anwenden: Nutzer-Edits einlesen, in den Vault neu projizieren.
tesserae vault sync

# Zuerst prüfen, was sich ändern würde. Schreibt .tesserae/diverged-fields.md und
# wendet NICHT an und projiziert nicht neu.
tesserae vault sync --dry-run

# Für diesen Aufruf einen bestimmten Vault angeben (Auflösungsreihenfolge:
# --vault > config.obsidian.vault_path > .tesserae/obsidian_vault/).
tesserae vault sync --vault ~/Documents/tesserae-vault

# Diesen Vault-Pfad zum Standard für künftige Befehle machen.
tesserae vault sync --vault ~/Documents/tesserae-vault --persist-vault

# Langlaufender Watch: Overlay bei jeder Vault-Änderung erneut anwenden.
# Ctrl-C zum Stoppen; --poll-interval steuert die Abtastrate (Standard 1,5 s).
tesserae vault sync --watch --poll-interval 1.5

# Projizierte Seiten löschen, deren Quell-Node nicht mehr existiert (der Projector
# überschreibt nur, löscht nie). Seiten mit User-Notes bleiben erhalten,
# sofern du nicht zusätzlich --force-prune-with-notes übergibst.
tesserae vault sync --prune-orphans
tesserae vault sync --prune-orphans --force-prune-with-notes

Der Slash-Befehl /tesserae:obsidian-sync umhüllt dies, und tesserae refresh (plus das /tesserae:refresh-Makro) führt das Overlay als letzten Schritt seiner import → compile → sync-Kette aus.

Lieferstatus

Nicht-Ziele (explizit)

• Ein Sync-Server / Auth / gehostetes Backend.
• Kollaboratives Echtzeit-Editing innerhalb von Obsidian (dafür LiveSync nehmen, falls nötig).
• Den Extractor umschreiben, sodass jedes Feld Round-Trip-fähig ist — die Quell-Markdown bleibt kanonisch für alles außerhalb der Override-Tabelle.
• Sync der statischen HTML-Site (build-site bleibt rein projektionsbasiert).

Getroffene Entscheidungen

Dies waren die offenen Fragen zur Designzeit; die ausgelieferte Tier-1–2-Implementierung hat sie wie folgt geklärt:

1. Form des Lint-Reports. Divergierte Felder tauchen als dedizierte Datei .tesserae/diverged-fields.md auf (geschrieben von --dry-run und bei jeder Anwendung), damit sie in Git diffbar bleibt, statt als Abschnitt von lint-report.md.
2. Tombstone-Node-Typ. Stub als echten Schematyp hinzufügen oder auf OpenQuestion mit einem Diskriminator _kind: stub aufsatteln? Vorschlag: echter Typ namens Stub, aus öffentlichen Indizes versteckt.
3. Pull-on-Compile-Default. Standardmäßig AN oder AUS? Vorschlag: AN, wenn am konfigurierten Pfad ein Vault existiert, mit einer einmaligen Bestätigungsabfrage beim ersten Auslösen, damit Nutzer bewusst zustimmen.
4. Was zählt für den Diff als „die vorherige Projektion"? Ein in .tesserae/vault_snapshot.json abgelegter Snapshot oder bei jedem Compile spontanes Re-Projizieren? Vorschlag: Snapshot, am Ende jedes Compiles geschrieben. Günstiger und vermeidet, dass Extractor-Nichtdeterminismus ins Overlay leakt.
5. Mehrsprachige Vault-Projektion. Heutige Projektion ist einsprachig (die Quelle). Sollen Overlays locale-aware sein (z. B. greift ein Edit an description in einem koreanischen Vault-Overlay nur auf die koreanische Projektion)? Vorschlag: außerhalb des Scopes für v1; der Vault ist einsprachig und folgt der primären Sprache des Projekts.

Wie sich das in obsidian.md zeigt

Der nutzergerichtete Guide bleibt fokussiert auf „du kannst den Vault lesen und abfragen" und verlinkt dann für die Round-Trip-Geschichte hierher, mit einer einzeiligen Zusammenfassung: „Felder in Obsidian bearbeiten, sie überleben das Recompile. Siehe obsidian-sync.md für das vollständige Modell."