Design #

Informal design documents: rationale, alternatives considered, and the why behind the architecture. Normative specifications live in specs/ (once anything here stabilizes enough to deserve one).

Doc	Question	Status
document-topology.md	How items map onto Automerge documents	Drafted
identity-and-dedup.md	What makes two deliveries the same event	Drafted
ingest-semantics.md	Redelivery vs. revision; ordering without trusted clocks	Drafted
polling-and-webhooks.md	Conditional GET, backoff, HMAC verification, replay	Drafted
sync-and-authz.md	Which peers sync what, over which transport	Drafted
retention.md	Pruning history; purge vs. tombstone	Drafted

Reading order #

Start at document topology: it defines the partition model everything else references. Identity and ingest semantics sharpen the ingest rules; polling, sync, and retention are the edges and mostly consume what the earlier docs decide. All six are drafted; the first three are the load-bearing ones.

Decisions in brief #

• One document per partition path; routing from item to path is a pure function, supplied by adapters (document topology).
• Dedup happens at ingest time, by map-key lookup on canonical identity (document topology, refined in identity and dedup).
• Ordering is derived at read time; nothing ordered is stored (document topology).
• Item storage is deliberately minimal — flat entries, no accessor machinery; client applications own interpretation, revision, and retention policy (document topology; consequences revisited in ingest semantics and retention).
• The inbound edge verifies everything (HMAC), acks before ingesting, and keeps poll state local — parallel polling is safe because dedup makes duplicate work harmless (polling and webhooks).
• Sync is prefix-subscription over WebSocket to a relay first; authorization is transport-local peer allowlists in v1, with Keyhive-backed capability grants deferred (sync and authorization).
• Retention: identity memory permanent, payloads prunable by client policy; logical prune vs. physical purge are distinct promises (retention).