Living Document Notice
Published 2026-11-02. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.
Handling Dirty State and Merge Conflicts
Summary
Offline text editing guarantees that distributed replicas will eventually diverge. When two devices modify the same markdown note simultaneously without network coordination, naive synchronization engines either overwrite changes silently or litter note text with destructive Git conflict markers. The Tender daemon pairs local write journals with remote Harbormaster heads to execute structural three-way merges.
Non-conflicting paragraph edits merge deterministically at the AST boundary. When edits collide on the same lines, the daemon preserves both versions by creating sidecar conflict notes, preventing corruption of the user’s active reading and writing flow.
The Reality of Offline Divergence
Local-first software treats network connectivity as an opportunistic synchronization mechanism rather than an operational requirement. Users edit meeting notes on laptops during flights, update task lists on phones in remote areas, and leave desktop sessions running at home.
When disconnected devices reconnect, the synchronization engine must reconcile divergent changes. Two primary failure modes plague existing synchronization tools:
- Last-Write-Wins (LWW): Silently overwriting files based on remote clock timestamps, destroying offline user edits.
- In-File Conflict Markers: Injecting raw Git markers (
<<<<<<< HEAD,=======,>>>>>>>) directly into note files, corrupting frontmatter and breaking Markdown parser rendering.
The Tender daemon implements deterministic three-way AST reconciliation, falling back to sidecar conflict files when line-level collisions occur.
+--------------------------------------------------------------------+
| Three-Way Reconciliation Flow |
| |
| [ Base Snapshot (Ancestor) ] |
| | |
| +----------------+----------------+ |
| | | |
| v v |
| [ Local Journal Edits ] [ Remote Harbormaster ] |
| (Uncommitted Working) (Incoming Server Head) |
| | | |
| +----------------+----------------+ |
| | |
| v |
| ( Three-Way AST Diff ) |
| | |
| [ Collision Detected? ] |
| / \ |
| No/ \ Yes |
| v v |
| [ Clean Auto-Merge ] [ Deterministic Branching ] |
| (Write to note.md) (Keep local note.md, |
| create note.sync-conflict.md) |
+--------------------------------------------------------------------+
Structural Three-Way Diffing
The daemon maintains a local base snapshot representing the state of the note at the last successful synchronization point. When an incoming change arrives from the Harbormaster KPP protocol, the daemon evaluates three artifacts:
- Base: Common ancestor revision (
O). - Local: Current workstation disk content (
A). - Remote: Incoming server payload (
B).
The reconciliation engine divides markdown documents into structural blocks: YAML frontmatter metadata, heading sections, and paragraph blocks.
pub enum MergeResult {
Clean(String),
Conflict {
merged_base: String,
local_divergence: String,
remote_divergence: String,
},
}
pub fn reconcile_blocks(base: &str, local: &str, remote: &str) -> MergeResult {
let diff_local = diff::lines(base, local);
let diff_remote = diff::lines(base, remote);
if !has_overlapping_hunks(&diff_local, &diff_remote) {
let merged_content = apply_non_overlapping(base, diff_local, diff_remote);
MergeResult::Clean(merged_content)
} else {
MergeResult::Conflict {
merged_base: base.to_string(),
local_divergence: local.to_string(),
remote_divergence: remote.to_string(),
}
}
}If the local user modified the frontmatter tags while a remote collaborator added a new paragraph under an existing heading, both changes apply automatically. The resulting merged text writes back to disk without user intervention.
Deterministic Branching for Hard Collisions
When local and remote changes alter the exact same paragraph or frontmatter key, automatic merging cannot proceed safely without guessing user intent.
Instead of inserting textual conflict syntax into the file, the Tender daemon activates deterministic conflict branching:
| Resolution Step | Action on Local Filesystem | Action on Transport Queue |
|---|---|---|
| Step 1: Retain Active File | Keep local version untouched (note.md) | Prevent local edit regression |
| Step 2: Write Sidecar Branch | Write remote version to note.sync-conflict-<DATE>-<HASH>.md | Ensure zero data loss |
| Step 3: Inject Frontmatter Links | Add cross-references in both frontmatter headers | Mark conflict status for UI review |
| Step 4: Notify Daemon Indexer | Schedule both files for graph indexation | Maintain link resolution in vault |
The sidecar conflict note uses a deterministic naming format:
<filename>.sync-conflict-<YYYYMMDD>-<SHORT_HASH>.md
---
title: "Project Notes"
sync_conflict:
base_revision: "7f8b9a1"
conflicting_with: "note.md"
detected_at: 2026-09-24T18:30:00Z
tags:
- sync-conflict
---
# Remote Divergent Content
[ Unmerged incoming lines preserved verbatim ]The user continues typing in note.md without interruption. The next time the user opens their note graph, the conflict note appears linked beside the original, allowing manual review and consolidation at leisure.
- Directus Target: tender
- Garden Source Reference: Three-Way Diff Engines, Harbormaster Synchronization, Deterministic Branching, MOC - Ingestion & Capture, MOC - Local-First Systems and Synchronization, MOC - Bosun PKM Tools, MOC - Harbormaster Protocol