BSN-1011 - The Bosun Architecture Foundation

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

The Bosun Architecture Foundation

Summary

Separating data persistence from application environments prevents note archives and other forms of personal data from becoming trapped in proprietary silos. When cloud services terminate operations or change licensing structures, users lose access to proprietary database stores and many of these users struggle to make use of the .xml, .csv, .json, .opml, or whatever the application was using behing the polished UI the user was familiar with.

Bosun isolates data persistence entirely within POSIX filesystems. By establishing plain-text UTF-8 files as the primary source of truth, application processes become interchangeable consumers rather than authoritative gatekeepers.

Filesystem Authority and Runtime Decoupling

Centralized knowledge applications traditionally bundle interface rendering, indexing logic, and storage persistence into an indivisible binary. In this monolithic pattern, notes are written to SQLite databases, RocksDB engines, or remote cloud document stores. When the binary fails, data recovery requires reverse-engineering binary serialization schemas or searching out a migration utility.

Bosun reverses this operational relationship. The local filesystem functions as the authoritative repository. Every document exists as an independent text file inside standard directory hierarchies. Applications interact with the vault through standard POSIX system calls: read(), write(), open(), and rename(). Secondary engines (search indexers, graph visualizers, static site generators, etc.)—read the filesystem passively and construct derived caches.

flowchart TD
    UserApp["User Application<br/>(Editor / Terminal / Agent)"]
    FS["Local POSIX Filesystem<br/>(UTF-8 Markdown + YAML Metadata)"]
    Index["Inverted Index<br/>(SQLite Cache)"]

    UserApp -->|1. POSIX Write| FS
    FS -->|2. Inotify / AST Parse| Index
    UserApp -->|3. IPC / Search Query| Index

If the search index corrupts or the user application crashes, the storage layer remains unaffected. A damaged SQLite cache is recovered by traversing the filesystem hierarchy and rebuilding the inverted index from source text.

Failure Modes of Cloud Document Stores

Cloud-backed note applications introduce systemic operational risks. Network latency interrupts write operations during intermittent connectivity. Authentication token expiration halts document access. Remote service changes can alter data models without user consent.

The table below contrasts the failure behaviors of remote multi-tenant document stores against local POSIX plain-text substrates.

Failure Domain	Multi-Tenant Cloud Store	Local POSIX Plain Text
Network Outage	Write queue stalls; synchronization blocks	Immediate local write to block device
Vendor Termination	Complete loss of unexported records	Files remain on local storage partition
Process Crash	Uncommitted transaction journal rollbacks	Written files preserved via atomic swap
Tool Incompatibility	Locked behind vendor API format	Universal access via standard shell tools
Schema Evolution	Remote migration required across tenants	Local incremental parse with fallback defaults

POSIX storage guarantees that data accessibility does not depend on remote server availability or commercial continuity.

Atomic Write Transactions on POSIX Filesystems

Writing directly to active files introduces the hazard of partial writes if a power loss or kernel panic occurs during execution. To maintain document integrity without a heavy database engine, Bosun enforces atomic write semantics using temporary staging files and atomic rename operations.

 
use std::fs::{File, rename};
use std::io::{Result, Write};
use std::path::Path;
 
pub fn atomic_write_document(target: &Path, content: &[u8]) -> Result<()> {
    let parent = target.parent().unwrap_or_else(|| Path::new("."));
    
    // 1. Stage in the same directory mount so the rename is an atomic inode swap
    let temp_path = parent.join(format!(".tmp_{:x}", fastrand::u64(..)));
    
    // 2. Write content and flush dirty OS page cache buffers to physical storage
    let mut file = File::create(&temp_path)?;
    file.write_all(content)?;
    file.sync_all()?;
    
    // 3. Atomically replace target path
    rename(&temp_path, target)?;
    
    // 4. Flush the parent directory to persist the updated directory entry
    #[cfg(unix)]
    {
        use std::os::unix::fs::OpenOptionsExt;
        let dir = std::fs::OpenOptions::new()
            .read(true)
            .custom_flags(libc::O_DIRECTORY)
            .open(parent)?;
        dir.sync_all()?;
    }
    
    Ok(())
}

The write pipeline executes sequentially:

1. Allocate a temporary sibling file in the same directory path to guarantee that both paths reside on the identical filesystem mount.
2. Flush user content and metadata to the temporary file descriptor, invoking sync_all() to flush dirty OS page cache buffers directly to non-volatile storage.
3. Execute rename(), which wraps the renameat system call. The operating system kernel replaces the target inode atomically.
4. On POSIX platforms, open the parent directory descriptor with O_DIRECTORY and invoke sync_all() to persist the updated directory entry modification.

The Invariant of Storage Independence

The storage foundation guarantees a single structural invariant: the deletion of all auxiliary caches, indexes, and background daemons must leave user document state intact and fully readable by /usr/bin/cat.

Audit inode state and permissions across the note repository using standard POSIX tooling:

stat -c "inode: %i | size: %s bytes | mod: %y | name: %n" "02 Review/bosun-pkm"/*.md

---

• Directus Target: bosunpkm-blog
• Garden Source Reference: MOC - Bosun PKM Engine, MOC - Bosun PKM Tools