TND-1001 - Local-First Without Isolation

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

Local-First Without Isolation

Summary

Local-first storage models provide absolute ownership of files, but total network isolation limits collaboration, public distribution, and automated backup workflows. Software that connects local files to remote edge networks often introduces synchronous network requests into local editor save routines, creating interface latency.

Tender operates as an unprivileged background sidecar daemon that bridges local disk storage to Harbor edge runtime edge HTTP caches. By listening asynchronously to Linux inotify and BSD kqueue notification streams, Tender coalesces rapid editing bursts into discrete changeset batches and synchronizes static publication assets without delaying local disk operations.

Asynchronous Edge Synchronization Architecture

Connecting local text files to web edge endpoints requires maintaining an asynchronous boundary. If saving a note triggers a synchronous HTTP POST request, local editing becomes dependent on network round-trip latency, DNS lookup times, and edge server health.

Tender decouples storage writes from network synchronization through a local staging queue. The local filesystem remains the primary writer target, while Tender observes mutations passively.

+-------------------------------------------------------------+
|                   Tender Event Pipeline                     |
|                                                             |
|  +-----------------------+                                  |
|  | Local Editor Save     |                                  |
|  | (Write -> Close File) |                                  |
|  +-----------------------+                                  |
|              |                                              |
|              v                                              |
|  [Kernel inotify / kqueue]                                  |
|              |                                              |
|              v                                              |
|  +-----------------------+       +-----------------------+  |
|  | Tender Event Queue    | ----> | Debounce Buffer       |  |
|  | (Thread Pool Monitor) |       | (300ms Coalesce)      |  |
|  +-----------------------+       +-----------------------+  |
|                                              |              |
|                                              v              |
|  +-----------------------+       +-----------------------+  |
|  | Edge HTTPS Dispatch   | <---- | AST Delta Extraction  |  |
|  | (Harbor CDN Ingest)   |       | ([Tree-sitter](https://tree-sitter.github.io/tree-sitter/) Parser)  |  |
|  +-----------------------+       +-----------------------+  |
+-------------------------------------------------------------+

When a user modifies a note, Tender absorbs the notification into an in-memory ring buffer. Successive modifications within a three-hundred millisecond window collapse into a single publication payload.

Event Coalescing and Ingestion Implementation

Rapid keystrokes or automated regex replacements can emit hundreds of filesystem events within milliseconds. Tender prevents network congestion by debouncing events per file path before initiating edge synchronization.

Event Type	Kernel Primitive	Buffer Policy	Synchronization Action
IN_CLOSE_WRITE	inotify	300ms debounce	Extract AST diff, stage for HTTPS dispatch
IN_MOVED_TO	inotify	Immediate dispatch	Record slug alias, update edge route mapping
IN_DELETE	inotify	500ms delay	Confirm removal, dispatch edge 404 tombstone

The following Go routine demonstrates the debounce worker loop utilized by the Tender daemon:

package watcher
 
import (
	"context"
	"sync"
	"time"
)
 
type DebounceQueue struct {
	mu       sync.Mutex
	pending  map[string]*time.Timer
	interval time.Duration
	out      chan<- string
}
 
func NewDebounceQueue(interval time.Duration, out chan<- string) *DebounceQueue {
	return &DebounceQueue{
		pending:  make(map[string]*time.Timer),
		interval: interval,
		out:      out,
	}
}
 
func (q *DebounceQueue) Enqueue(path string) {
	q.mu.Lock()
	defer q.mu.Unlock()
 
	if timer, exists := q.pending[path]; exists {
		timer.Stop()
	}
 
	q.pending[path] = time.AfterFunc(q.interval, func() {
		q.mu.Lock()
		delete(q.pending, path)
		q.mu.Unlock()
		q.out <- path
	})
}

This implementation prevents intermediate save states from flooding edge network endpoints. Only stable file saves produce edge synchronization requests.

Daemon Deployment and Monitoring

System administrators configure Tender as a user-level systemd service running in user session space:

# Verify Tender service state under user systemd manager
systemctl --user status tender.service
 
# Stream structured JSON logs from the Tender file monitor
journalctl --user -u tender.service -f -o json | jq '{timestamp: .__REALTIME_TIMESTAMP, path: .PATH, event: .EVENT}'

Operational Failure States

Bridging local disk writes to edge publication endpoints exposes predictable failure modes:

1. Kernel Watch Limit Depletion: On large repositories, inotify instances fail with ENOSPC when the directory count exceeds kernel watch allocations, requiring automated fallback to periodic polling.
2. Network Partition Buffering: Prolonged internet disconnects cause the outgoing dispatch queue to accumulate memory allocations, requiring a persistent disk-backed FIFO queue to avoid memory exhaustion.
3. Edge Token Expiration: Stale bearer authentication tokens cause synchronization requests to receive HTTP 401 responses, necessitating automated token renewal handshakes without blocking file watch loops.

---

• Directus Target: tender
• Garden Source Reference: BPT-1001 - The Bosun Architecture Manifesto, [HAR-1001 - Ditching the Full-Stack SSR Monolith](HAR-1001 - Ditching the Full-Stack SSR Monolith), MOC - Ingestion & Capture, MOC - Local-First Systems and Synchronization, MOC - Bosun PKM Tools, [OUT-1001 - Verifying Autonomous Agent Bounds with Pure Standard Library](OUT-1001 - Verifying Autonomous Agent Bounds with Pure Standard Library), MOC - Bosun PKM Engine, MOC - Harbor Ecosystem