Design #

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

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.

partition-discovery.md is gone. It designed a registry document, partition claims, settle windows, and discard-and-replay to stop two stations from minting rival documents for one path. A deterministic genesis change removes the possibility instead of managing it (below), so the document described machinery that no longer has a problem to solve. The reasoning survives in ADR-0016 and ADR-0018.

These documents describe the design as it stands. Where one records a decision that was later reversed, the reversal is stated in place — trade-off history lives in the decision ledger, not here.

Decisions in brief #

• One document per partition path; routing from item to path is a pure function, supplied by adapters (document topology).
• Identity is (partition, origin id), hashed with BLAKE3 over a length-prefixed, domain-separated field stream; dedup happens at ingest time, by map-key lookup on canonical identity (document topology; identity and dedup).
• A partition document's identity is a function of its path. Genesis is written by a path-derived actor at time zero, so two stations that have never met mint byte-identical documents. There is no registry, no claim, and no origin to elect (document topology).
• The document schema is flat: every value is a root-level scalar. Nested maps read better and lose data — concurrent put_object calls mint rival objects, and a merge discards one subtree whole, revoking commits a station had already accepted (document topology; review).
• Ordering is derived at read time; nothing ordered is stored. (first_received_at, identity_hash) is total, so no sequence number is kept (ingest semantics).
• Client applications own interpretation, revision, and retention policy (document topology; consequences revisited in ingest semantics and retention).
• The inbound edge verifies everything (HMAC), acks only after the payload is durably queued, 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).