InternalArchitecture

Sync Model

Append-only change log, client outbox, cursor-based pull, and canonical pull→apply→push order.

7. Sync model

7.1 Append-only change log

Conceptual schema:

changes (
  id        BIGSERIAL,
  stream    TEXT,
  entity    TEXT,
  entity_id TEXT,
  kind      TEXT,
  patch     JSON,
  tags      JSON,
  hlc       TEXT
)

Properties:

immutable
ordered
cursor-addressable

7.2 Client outbox

Clients maintain an outbox of local changes:

append-only
retried until acknowledged
idempotent

7.3 Cursor-based pull

pull(stream, cursor) -> { changes[], nextCursor }

This is the only correctness mechanism. Realtime is optional.

7.4 Canonical sync order

Pull → Apply → Push

Why:

incorporate remote truth first
reapply local intent
resolve conflicts deterministically

Core Data Model

Change as the replication primitive, HLC format, field-level LWW, and tombstones.

Query Model & Invalidation

Why row queries can be precise, list queries must be rerun, and sorting is the same class as filtering.