pb-offline-sync v0.1-alpha
code
ENGINE RUNTIME: ATOMIC DUAL-JOURNAL
SPEC REV: 2025.04-FROZEN
01 // PROTOCOL & TOPOLOGY · HIGH-DETERMINISM REPLICATION

Architecture & Transaction Guarantees

Deterministic two-way replication protocol between client outboxes and PocketBase sync_changes journal. Built for zero-loss offline runtimes with explicit sequence monotonicity.

TIER I: CLIENT (EDGE) ➔ TIER II: STATELESS WIRE (HTTP/SSE) ➔ TIER III: POCKETBASE GO RUNTIME
CONCURRENCY MODEL: SEQUENTIAL_WAL
devices Client Runtime
OFFLINE READY

Local embedded persistent storage with immediate optimistic rendering and transactional mutation outbox.

Application UI / Business Logic
User interaction / Direct view model writes
touch_app
arrow_downward
SyncEngine Client Daemon v0.1.4-client

Intercepts mutations, assigns immutable client UUIDs, manages backoff queues, and hydrates downstream patches.

south commit local south queue delta
database Local SQLite
Optimistic user state ready for instantaneous queries (0ms UI latency).
list_alt _outbox Queue
Pending ordered mutation records: UUID, op, delta.
Local Cache: 1,420 rows Unsent Outbox: 2
swap_horiz Wire Protocol Bridge
RECOVERY & PUSH

Stateless transport pipeline managing deduplication, partial batch retries, and realtime invalidation nudges.

arrow_upward UPSTREAM PUSH POST /api/sync/push

Idempotent batch transaction with client mutation UUIDs. PocketBase ignores previously applied sequence hashes.

Payload: { mutations: [{ client_uuid, table, delta }] }
arrow_downward DOWNSTREAM PULL GET /api/sync/pull?since={seq}

High-efficiency retrieval of committed server changes since client's last verified authoritative monotonic sequence.

Response: { cursor: 18492, changes: [...], has_more: false }
bolt REALTIME SIGNAL SSE Nudge Stream

Thin lightweight wake ping. PocketBase alerts connected clients that mutations arrived: client fires pull. No data in SSE payload.

notifications_active pocketbase.onRecordUpdate -> nudge "pull now"
Transfer Enc: gzip/zstd Idempotency: STRICT
dns PocketBase Host
AUTHORITATIVE

Go-based runtime embedding native SQLite transactions with synchronous change journaling hooks.

pb_offline_sync Plugin Go v1.23

Hooks into PocketBase DAO lifecycle: intercepts OnModelBeforeCreate/Update/Delete.

sync_alt
lock ATOMIC TX ENVELOPE BEGIN EXCLUSIVE
Application Tables posts, tasks, notes ✓ State Mutated
sync_changes Journal seq, rev, delta, client_uuid ✓ Monotonic Incr
COMMIT: Both writes succeed or both roll back together
Authoritative Sequence seq = 18492
Guarantees zero skipping and complete historical pull replays.
verified WAL Enabled Dedup Window: 7 days
memory ACTIVE TRANSACTION PIPELINE & WIRE PROTOCOL TRACE · LIVE DEDUPLICATION AUDIT
FILTER: COMMITTED_ATOMIC
[10:42:01.004] [CLIENT] Local mutation enqueued: notes/uuid-7a8b-11f2 (title: "Field Inspection Notes")
[10:42:01.006] [WIRE] POST /api/sync/push { client_uuid: "mut-9081", base_rev: 412, table: "notes" }
[10:42:01.018] [PB-HOST] SQLITE TX EXCLUSIVE: Inserted record `notes.rec_x91` & logged `sync_changes.seq=18493` [12ms]
[10:42:01.020] [NUDGE] SSE broadcast payload: { event: "sync:nudge", seq: 18493 } dispatching to 3 subscribed peers
verified_user
Atomicity Invariant & Monotonic Contract · Zero Orphaned Deltas

Every mutation (client push, standard PocketBase REST API, or PocketBase Admin UI) is captured in the same transaction as the data write. If the write aborts, no sync entry is recorded. If it commits, replays are strictly deduplicated by the engine runtime.

GUARANTEE METRICS
2PC-FREE / ATOMIC WAL / DEDUP: EXACTLY-ONCE
02 // SCOPED NON-GOALS FOR v0.1

Deliberate Architectural Boundaries

To maintain extreme determinism and zero-edge corruption in early versions, complex distributed consensus modes are explicitly deferred.

EXCLUDED: MULTI-USER WRITE group_off

Shared / Multi-User Write Records

Strictly per-user record ownership. Documents belong to exactly one user partition. Collaborative real-time document co-authoring is explicitly out of scope for v0.1.

Constraint: Record.owner == Auth.id
EXCLUDED: BINARY BLOBS cloud_off

File & Binary Content Sync

Large media and binary blobs do not travel through the mutation outbox or sync_changes table. Handled independently via signed direct upload URLs.

Payload Limit: Structured JSON < 512KB
EXCLUDED: OP MUTATIONS calculate

Operation Mutations / Distributed Counters

No delta math operators like INCREMENT(likes, 1). The protocol synchronizes state values, not operational execution logic.

Model: State Replacement, not Op-Log
EXCLUDED: CRDT GRAPHS account_tree

Complex CRDT Trees (Yjs / Automerge)

Deterministic Last-Write-Wins (LWW) field patch evaluation chosen deliberately for absolute code simplicity and transparent SQLite column inspection.

Resolution: Server Clock Monotonic LWW
EXCLUDED: MERGE HOOKS merge_type

Custom Server-Side Merge Handlers

No complex three-way interactive merge UI on the host. PocketBase acts as an immutable sequence log and authoritative rev assigner.

Arbitration: Strict Authoritative Sequence
EXCLUDED: EMBEDDED PB mobile_off

Running PocketBase Binaries on Edge Devices

PocketBase runs on your server. Mobile/Web clients run tiny SQLite or IndexedDB adapters via standard TypeScript SDKs, not compiled Go binaries.

Client Weight: ~18KB TypeScript Core
03 // FROZEN ARTIFACTS & CONTRACTS

Protocol Specifications & Interface Definitions

FROZEN v1.0 CONTRACT · SEMVER STRICT
docs/protocol.md 32.4 KB · MD

Wire Protocol & Change Journal Schema

Complete wire spec defining HTTP endpoints, error envelope schemas, JSON patch formatting (RFC-6902 subset), and monotonic cursor pagination semantics.

SHA256: 7f8a9...b41e
visibility View Protocol
docs/architecture.md 48.1 KB · MD

PocketBase Plugin & SQLite Hook Internals

Deep architectural breakdown of the Go plugin implementation, SQLite transaction hooks, WAL mode locking guarantees, and outbox reconciliation lifecycles.

SHA256: e921c...81d0
visibility View Architecture