Writer's Guide: Overview

This section covers everything a writer needs to know: how to connect, write data, maintain data integrity across reconnections, and handle multi-source convergence.

Writer lifecycle

A typical writer follows this lifecycle:

1. Connect. Establish a TCP connection with a unique SourceId (0 to 63). The server begins tracking this source’s liveness.

2. Register schemas. Call RegisterKindAsync<T>() for each entity kind the writer will use. This is safe to call on every startup.

3. Write data. Use AssertAsync, PatchAsync, and RetractAsync to declare entity state. Writes are fire-and-forget with no per-operation acknowledgement.

4. Maintain integrity. When the writer receives a new full-state snapshot from an upstream data source (for example, after reconnecting to an upstream database), use Source Epochs to reconcile stale assertions.

5. Disconnect. When the connection is lost, the server starts a liveness countdown (default: 30 seconds). If the writer does not reconnect within the deadline, all entities with only this source’s bit are tombstoned.

Pages in this section

Page	What it covers
Assert, Patch, and Retract	Precise semantics of all three write operations, including how they interact with versions, source bits, and subscriber notifications.
Multi-Source Convergence	How source bitsets work, how multiple services can write to the same entity kind, and how deduplication prevents redundant notifications.
Write Coalescing	How the server batches writes within a time window, what this means for notification latency, and when coalescing helps most.
Batching	Client-side write batching for efficient bulk updates.
Metadata Passthrough	Attaching opaque causal metadata to writes, and how subscribers receive it.
Source Epochs	The epoch protocol for reconciling stale assertions after reconnection, including edge cases and interaction with retraction.