LOG-1001 - Append-Only Temporal Logs vs. Destructive Note Overwrites

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

Append-Only Temporal Logs vs. Destructive Note Overwrites

Daily notes in conventional personal knowledge systems suffer from state clobbering. When an application mutates a daily document in place, any mid-flight write during network partitions or simultaneous process writes risks truncating historic telemetry. The Bosun Logbook subsystem treats daily journal files as immutable, append-only chronological ledgers.

The Append-Only Invariant

In standard operating systems, appending to an open file descriptor using the O_APPEND flag guarantees atomic writes to the end of the file across multiple concurrent processes:

#include <fcntl.h>
#include <unistd.h>
#include <string.h>
 
int append_log_entry(const char *filepath, const char *entry_buf, size_t len) {
    int fd = open(filepath, O_WRONLY | O_CREAT | O_APPEND, 0644);
    if (fd < 0) {
        return -1;
    }
    ssize_t written = write(fd, entry_buf, len);
    close(fd);
    return (written == (ssize_t)len) ? 0 : -1;
}

By decoupling intake from destructive file rewrites, journal entries retain their exact ingestion sequence without requiring complex lock management or background SQLite transactional rollbacks.

Temporal Ledger Record Format

Each log entry constitutes a distinct semantic block demarcated by an ISO 8601 UTC timestamp header and YAML attribute block:

### 2026-09-17T14:22:05Z - Intake
event_type: checkpoint
latency_budget_ms: 15
source: terminal_cli
---
Encountered memory pressure during columnar table compilation.
Allocated 4 MiB buffer to buffer ring.

When new thoughts, measurements, or system notifications occur, the intake engine formats the block and executes a direct append. At no point does the client parse or rewrite prior hours within the active day note.

Write-Amplification Mitigation

Destructive overwriting of a 50 KiB markdown journal file to add a 120-byte observation generates severe write-amplification on solid-state flash media. Append-only writes isolate mutations to the tail sector, allowing OS page caches to aggregate dirty blocks efficiently:

Storage Pattern	Daily Writes (100 Entries)	Flash Write Amplification	Process Lock Contention
Full-File Rewrite	5.0 MB	41.6x	High (Read-Modify-Write)
Append-Only Tail	120 KB	1.0x	Zero (O_APPEND Atomic)

The append-only architecture ensures sub-millisecond execution times and leaves historical daily archives impervious to data loss caused by parser panics.

---

• Directus Target: logbook
• Garden Source Reference: MOC - Daily Log & Chronological Journal, MOC - Bosun PKM Tools
• Garden Source Reference: LOG-1001 - Append-Only Temporal Logs vs. Destructive Note Overwrites