Bidirektionale Obsidian-Synchronisation — vorgeschlagener Entwurf

<!-- translations:start -->

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

<!-- translations:end -->

Status: Vorschlag (2026-05-17). Dieses Dokument ist eine Design-Spezifikation, noch kein Feature. Es beschreibt, wie Tesserae es Nutzern ermöglichen könnte, projizierte Wiki-Seiten in Obsidian zu bearbeiten und diese Änderungen das nächste project compile überleben zu lassen. Die Implementierung hängt davon ab, dass dieser Entwurf landet.

Aktuell ist der Obsidian-Export strikt einseitig: Der typisierte Graph in .tesserae/graph.json projiziert in den Vault, und project compile überschreibt projizierte Dateien. Nutzer haben auch nach der Gegenrichtung gefragt — eine Beschreibung in Obsidian bearbeiten und sehen, dass sie das Recompile überlebt.

Dieses Dokument legt dar, wie das funktionieren würde, 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 (vorgeschlagen)

# 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

Phasen

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).

Offene Entscheidungen vor der Implementierung

Diese haben vorgeschlagene Defaults, verdienen aber einen finalen Durchgang, bevor Code landet:

1. Form des Lint-Reports. Sollen divergierte Felder als separate Datei .tesserae/diverged-fields.md auftauchen oder als neuer Abschnitt im bestehenden lint-report.md? Vorschlag: dedizierte Datei, damit sie in Git diffbar bleibt.
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". Ein kurzer Abschnitt „Bidirektionale Synchronisation" am Ende wird hierher verlinken, sobald die Implementierung landet, mit einer einzeiligen Zusammenfassung: „Felder in Obsidian bearbeiten, sie überleben das Recompile. Siehe obsidian-sync.md für das vollständige Modell."

Bis dahin bleibt der bestehende Read-only-Disclaimer in obsidian.md stehen — dieser Entwurf ist eine Roadmap, kein ausgeliefertes Feature.