Commit 084dacf
docs: pseudo-merge mode academic article
Adds docs/PSEUDO-MERGE-MODE.md (~10k words): a design-rationale
article for the conflict-resolution layer, written for a
technically-curious Obsidian user rather than for plugin developers.
Structure:
- Abstract + §1 problem framing (vault sync without git)
- §2 minimum-viable git model (blob, tree, commit, HEAD, branch,
merge-commit, reachability) — only what later sections need
- §3 why the conventional resolution toolkit (markers, modals,
refusal) fails on this constraint set
- §4 core idea — auto-merge first, then sibling files + per-device
conflict branch; §4.4 highlights preserve-all-commits as a
first-class design goal
- §5 three-layer architecture (sync polling, counter event-driven
read-only, resolution drain-start only)
- §6 modify-vs-modify / delete-vs-modify / modify-vs-delete
asymmetry
- §7 auto-merge dispatch table (text 3-way, plugin-js semver,
binary always-register)
- §8 edit-while-in-conflict — distinguishing feature with full
branch-state diagram
- §9 crash protection — `.sync-tmp` (forward target, ownership-
dispatched across Path A pull-replace + Path B sibling
registration) and `.sync-bak` (rollback target, Path A only,
no dispatch). 5-step + 3-step protocols, crash matrices, and
the unified two-pass recovery sweep
- §10 four scenarios on the running example (Notes/idea.md on
Laptop + Phone): simple conflict, long-offline accumulated
edits, multi-device multi-sibling, crash mid-create
- §11 what pseudo-merge does NOT promise
- §12 glossary (20 terms)
Running example threads through §6, §8, and all four scenarios for
narrative continuity. ASCII diagrams in §2.1, §4.2, §8, §9.
Source matches code after the .sync-tmp/.sync-bak semantic split
landed in 2a383f4. Markdown-lint table-alignment warnings are
cosmetic (source-column widths); GFM rendering is correct.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>1 parent 2a383f4 commit 084dacf
1 file changed
Lines changed: 1331 additions & 0 deletions
0 commit comments