Stax Digital Garden

LOG-1003 - Incremental CalDAV VEVENT Sync Without Full-Document Rewrites

2 min read

Living Document Notice
Published 2026-09-17. The evolving architecture, revisions, and connected notes for this dispatch live in the Stax Digital Garden.

Incremental CalDAV VEVENT Sync Without Full-Document Rewrites

Incremental CalDAV VEVENT Sync Without Full-Document Rewrites: Dual-trace Phosphor P7 monochromatic ice blue and P4 paper white vector CRT macro showing CalDAV VEVENT delta synchronization sweeps, XML token boundary lines, and ETag validation pulse sequences

Integrating calendar servers with local daily notes frequently leads to merge conflicts. Naive synchronization tools download remote ICS calendars and overwrite entire schedule sections inside markdown files. The Bosun Logbook uses an incremental CalDAV VEVENT delta sync daemon that operates directly against a local SQLite cache and emits surgical byte patches.

ETag Validation and Delta Harvesting

The sync supervisor queries the CalDAV endpoint using the calendar-multiget XML report, requesting only items whose remote getetag differs from the local cache:

import xml.etree.ElementTree as ET
import urllib.request
 
def fetch_changed_vevents(caldav_url, token, known_etags):
    body = (
        '<?xml version="1.0" encoding="utf-8" ?>\n'
        '<C:calendar-query xmlns:D="DAV:" xmlns:C="urn:ietf:params:xml:ns:caldav">\n'
        '  <D:prop>\n'
        '    <D:getetag/>\n'
        '    <C:calendar-data/>\n'
        '  </D:prop>\n'
        '  <C:filter>\n'
        '    <C:comp-filter name="VCALENDAR">\n'
        '      <C:comp-filter name="VEVENT"/>\n'
        '    </C:comp-filter>\n'
        '  </C:filter>\n'
        '</C:calendar-query>'
    )
    
    req = urllib.request.Request(
        caldav_url,
        data=body.encode("utf-8"),
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/xml",
            "Depth": "1"
        },
        method="REPORT"
    )
    with urllib.request.urlopen(req) as resp:
        return resp.read()

When an event changes, the daemon updates the local relational store rather than writing into today’s markdown file.

Decoupling Calendar State from Markdown Files

Separating remote calendar synchronization from the daily journal yields three architecture guarantees:

[Remote CalDAV Server]
         │
    (REPORT sync)
         ▼
[Local SQLite Cache] ──(In-Memory Query)──> [Marlinspike CST Engine]
                                                    │
                                            (Virtual Overlay)
                                                    ▼
[Local Daily Note Disk File] ───────────────> [Rendered View]
  1. Zero Merge Conflicts: Git branches and synchronization daemons never fight over concurrent edits in daily files.
  2. Offline Resilience: The rendered view queries the local SQLite cache without blocking on remote HTTP handshakes.
  3. Pristine Markdown: Daily notes contain only user-authored journal entries and explicit query directives.
  • Directus Target: logbook
  • Garden Source Reference: MOC - Daily Log & Chronological Journal, MOC - Bosun PKM Tools
  • Garden Source Reference: [LOG-1003 - Incremental CalDAV VEVENT Sync Without Full-Document Rewrites](LOG-1003 - Incremental CalDAV VEVENT Sync Without Full-Document Rewrites)

Graph View