SDK API Reference

ConvergenceOptions

Passed to ConvergenceClient.ConnectAsync().

Property	Type	Default	Description
`Host`	`string`	required	Server hostname or IP address.
`Port`	`int`	required	Server TCP port (default ConvergeDB port: 3727).
`SourceId`	`byte?`	`null`	Optional writer identity (0-63). When `null` the server allocates the lowest free slot and surfaces it as `ConvergenceClient.SourceId` after connect. Set to a specific value to claim it explicitly — useful for role-mapped writers or for reconnecting to recover preserved entities. A claim conflict throws `ConnectClaimConflictException`.
`ReadOnly`	`bool`	`false`	When `true` the connection is read-only: it does not consume a source_id slot, is absent from the `convergedb_connections` system kind, and mutating calls throw `ReadOnlyOperationException` locally. Mutually exclusive with `SourceId`.
`Name`	`string?`	`null`	Human-readable name for this client. Visible to other clients via the `convergedb_connections` system kind. See Client Presence.
`AuthToken`	`string?`	`null`	Authentication token sent in the CONNECT frame.
`LivenessDeadlineMs`	`uint`	`30000`	How long the server preserves this client’s entities after disconnect before retracting them. Must be greater than `HeartbeatIntervalMs`.
`HeartbeatIntervalMs`	`int`	`15000`	How often the client sends a heartbeat to keep the connection alive.
`ReconnectMaxDelayMs`	`int`	`10000`	Maximum reconnection back-off delay.
`SubscriberBufferSize`	`int`	`4096`	Bounded capacity of each subscription’s internal notification channel. Applies to live notifications only; during bootstrap the SDK applies backpressure.

ConvergenceClient

Property	Type	Description
`SourceId`	`byte?`	The source_id confirmed by the server after `ConnectAsync`. `null` for read-only clients.
`IsReadOnly`	`bool`	`true` when opened with `ConvergenceOptions.ReadOnly`. Mutating methods throw `ReadOnlyOperationException` when this is `true`.
`Connections`	`KindHandle<ConvergeDbConnection>`	Pre-resolved handle for the built-in `convergedb_connections` system kind. Subscribe to observe connected clients. See Client Presence.

Connection exceptions

Exception	Thrown by	Meaning
`ConnectClaimConflictException`	`ConnectAsync`	The requested `SourceId` is currently held by another live connection.
`ConnectExhaustedException`	`ConnectAsync`	All 64 source_id slots are in use; retry when a writer disconnects.
`ReadOnlyOperationException`	mutating SDK calls	A read-only client attempted `AssertAsync` / `RetractAsync` / `PatchAsync` / `CreateKindAsync` / `EpochBeginAsync` / `EpochEndAsync`. Also surfaced if the server rejects a mutating frame under defence-in-depth.

Method	Returns	Description
`ConnectAsync(options)`	`ConvergenceClient`	Connect to a ConvergeDB server.
`RegisterKindAsync<T>()`	`KindHandle<T>`	Register an entity kind (writers), returns a typed handle. Storage mode (in-memory or disk-backed) is determined by the `[ConvergenceEntity]` attribute.
`ResolveKindAsync<T>()`	`KindHandle<T>`	Resolve a kind without mutation (readers). Validates the client’s schema is a compatible prefix of the server’s.
`CreateKindAsync(name, fields)`	`ushort`	Low-level: create entity kind, returns KindId.
`GetKindAsync(name, fields)`	`GetKindResult`	Low-level: read-only schema resolution, returns KindId + schema version + field count.
`AssertAsync(kindId, entityId, fieldData)`	`Task`	Low-level: buffer an Assert (requires `FlushAsync`).
`PatchAsync(kindId, entityId, fieldData, mask)`	`Task`	Low-level: buffer a Patch (requires `FlushAsync`).
`RetractAsync(kindId, entityId)`	`Task`	Low-level: buffer a Retract (requires `FlushAsync`).
`FlushAsync()`	`Task`	Flush all buffered writes. Uses a single BATCH frame when >1 op is buffered.
`Batch()`	`ConvergenceBatch`	Create a cross-kind batch that flushes on dispose.
`QueryAsync(kindId, entityId)`	`EntityQueryResult`	Low-level: point read.
`SubscribeAsync(kindId, bootstrap, includePrevious, reconnectMode)`	`SubscriptionHandle`	Low-level: subscribe to a kind.
`EpochBeginAsync()`	`Task`	Begin a source epoch.
`EpochEndAsync()`	`Task`	End a source epoch, retracting stale entities.
`EpochAsync(Func<Task>)`	`Task`	Convenience: Begin + callback + End.

GetKindResult

Returned by client.GetKindAsync().

Property	Type	Description
`KindId`	`ushort`	The server’s kind ID.
`SchemaVersion`	`byte`	The server’s current schema version.
`FieldCount`	`ushort`	Total field count on the server (may exceed the client’s known fields).

KindHandle<T>

Obtained via client.RegisterKindAsync<T>() (writers) or client.ResolveKindAsync<T>() (readers). Thread-safe singleton.

Method	Returns	Description
`AssertAsync(entity)`	`Task`	Assert a typed entity (auto-flush).
`AssertAsync(entity, metadata)`	`Task`	Assert with metadata.
`PatchAsync(patch)`	`Task`	Patch a typed entity (auto-flush).
`PatchAsync(patch, metadata)`	`Task`	Patch with metadata.
`RetractAsync(entityId)`	`Task`	Retract a typed entity (auto-flush).
`RetractAsync(entityId, metadata)`	`Task`	Retract with metadata.
`QueryAsync(entityId)`	`T?`	Typed point read. Returns null if not found.
`SubscribeAsync(bootstrap, includePrevious, reconnectMode, ct)`	`IAsyncEnumerable<EntityChange<T>>`	Typed subscription.
`Batch()`	`KindBatch<T>`	Single-kind batch that flushes on dispose.
`BootstrapSnapshotAsync(ct)`	`IReadOnlyList<T>`	One-shot bootstrap: subscribe, collect, unsubscribe.
`SubscribeEventsAsync(ct)`	`IAsyncEnumerable<EntityEvent<T>>`	Subscribe to per-assert events. The kind must have been registered with `EventStream = true`. Returns individual operation events (not coalesced state). No bootstrap is available since events are ephemeral. See Event Streams for details.

EntityChange<T>

Yielded by KindHandle<T>.SubscribeAsync().

Property	Type	Description
`Type`	`NotificationType`	Created, Updated, Deleted, or Bootstrap.
`Entity`	`T?`	Current entity state. Null for Deleted.
`PreviousEntity`	`T?`	Previous state (only for Updated with `includePrevious`).
`EntityId`	`ReadOnlyMemory<byte>`	The 32-byte entity ID.
`Version`	`ulong`	Monotonically increasing per entity.
`SourceSet`	`ulong`	Bitmask of asserting sources.
`ChangedFields`	`ulong`	Bitmask of fields that changed.
`Metadata`	`ReadOnlyMemory<byte>`	Opaque metadata from the write operation.

Method	Returns	Description
`HasChanged(int fieldIndex)`	`bool`	Check if a specific field changed.

EntityEvent<T>

Yielded by KindHandle<T>.SubscribeEventsAsync().

Property	Type	Description
`Type`	`EventType`	Created, Updated, or Retracted.
`Version`	`ulong`	Committed entity version from the flush cycle.
`PrevVersion`	`ulong`	Committed entity version before this flush cycle. 0 for Created.
`SourceId`	`byte`	Which source (0-63) produced this operation.
`Sequence`	`ulong`	Partition-global monotonic sequence number.
`Entity`	`T?`	Deserialized assert payload (null for Retracted). This is the raw assert data, not the converged state.
`PreviousEntity`	`T?`	For Updated: previous state that `ChangedFields` was computed against. For Retracted: entity state before retraction. Null for Created. Forms a diff triple with `Entity` and `ChangedFields` for Updated events.
`ChangedFields`	`ulong`	Bitmask of fields changed by this assert. MaxValue for Created, 0 for Retracted.
`PresenceMask`	`ulong`	For PATCH: which fields were present.
`Metadata`	`ReadOnlyMemory<byte>?`	Opaque metadata from the assert/retract.

Method	Returns	Description
`HasChanged(int fieldIndex)`	`bool`	Check if a specific field was changed by this assert.

SubscriptionHandle

Returned by the low-level client.SubscribeAsync().

Property / Method	Type	Description
`KindId`	`ushort`	The subscribed kind.
`BootstrapStatus`	`BootstrapState`	Current bootstrap state.
`BootstrapEntityCountHint`	`uint`	Approximate entity count from BOOTSTRAP_BEGIN.
`BootstrapStatusChanged`	`event Action<BootstrapState>`	Fires on each state transition.
`ReadAllAsync(ct)`	`IAsyncEnumerable<ChangeNotification>`	Read notification stream.
`RebootstrapAsync(ct)`	`Task`	Trigger manual re-bootstrap.
`WaitForBootstrapCompleteAsync(ct)`	`Task`	Wait until bootstrap finishes.

EventSubscriptionHandle

Returned by the low-level client.SubscribeEventsAsync().

Property / Method	Type	Description
`KindId`	`ushort`	The subscribed kind.
`ReadAsync(ct)`	`ValueTask<EventNotification>`	Read the next event notification.
`ReadAllAsync(ct)`	`IAsyncEnumerable<EventNotification>`	Read event notification stream.
`TryRead(out notification)`	`bool`	Non-blocking read attempt.
`DisposeAsync()`	`ValueTask`	Unsubscribe and release resources.

No bootstrap support. Events are ephemeral.

EntityQueryResult

Returned by client.QueryAsync().

Property	Type	Description
`Status`	`QueryStatus`	Alive, Tombstone, or NotFound.
`FieldData`	`ReadOnlyMemory<byte>?`	Raw field data (only for Alive).
`Version`	`ulong`	Entity version.
`SourceSet`	`ulong`	Source bitmask.

Enums

NotificationType

Value	Description
`Created`	Entity was created (or re-created from tombstone).
`Updated`	Entity field data changed.
`Deleted`	Entity was tombstoned.
`Bootstrap`	Entity snapshot from bootstrap scan.
`BootstrapComplete`	Sentinel: the bootstrap snapshot is fully delivered. `Entity` is null. Also emitted after re-bootstrap.

EventType

Value	Description
`Created` (1)	First assert for a previously non-existent entity.
`Updated` (2)	Assert that modifies an existing entity.
`Retracted` (3)	Source retracted its assertion. `PreviousEntity` contains the pre-retraction entity state.

EventType.Retracted differs from NotificationType.Deleted: a retraction event fires for every individual retract operation regardless of whether the entity dies, while a Deleted notification only fires when all sources have retracted (entity becomes tombstoned).

QueryStatus

Value	Description
`Alive`	Entity exists and has field data.
`Tombstone`	Entity retracted by all sources, within retention period.
`NotFound`	Entity never existed or tombstone expired.

BootstrapState

Value	Description
`NotRequested`	Bootstrap was not requested or has not started.
`InProgress`	BOOTSTRAP_BEGIN received, scan in progress.
`Complete`	BOOTSTRAP_END received, initial bootstrap done.
`RebootstrapInProgress`	Re-bootstrap in progress (after reconnection).
`RebootstrapComplete`	Re-bootstrap done (after reconnection).

ReconnectBootstrapMode

Value	Description
`LiveOnly`	Resume live-only after reconnect. Gap during disconnect is lost.
`Full`	Re-subscribe with bootstrap after reconnect. Zero-drift guarantee.

IConvergenceEntity<T>

Generated by the source generator for each [ConvergenceEntity] struct.

Member	Kind	Description
`KindName`	`static string`	The kind name registered with the server.
`Schema`	`static KindSchema`	The field schema used for registration.
`FixedFieldDataSize`	`static int`	Size in bytes of the fixed zone (scalars, fixed-length strings/bytes, structs) plus the array directory (4 bytes per variable-length field). For kinds with no variable-length fields, this equals the total field data size.
`HasVariableLengthFields`	`static bool`	Whether this kind has any Array, VarString, or VarBytes fields.
`EntityId`	`ReadOnlyMemory<byte>`	The 32-byte entity ID.
`ComputeFieldDataSize()`	`int`	Compute the total field data size for this entity instance, including packed array/VarString/VarBytes data. For kinds with no variable-length fields, returns `FixedFieldDataSize`.
`WriteTo(Span<byte>)`	`void`	Serialize fields into a buffer of `ComputeFieldDataSize()` bytes.
`ReadFrom(ReadOnlySpan<byte>, ReadOnlyMemory<byte>)`	`static T`	Deserialize an entity from raw field bytes.
`ReadFrom(ReadOnlySpan<byte>, ReadOnlyMemory<byte>, ushort, ushort)`	`static T`	Deserialize with server layout hints (for evolved schemas).

Attributes

Attribute	Target	Description
`[ConvergenceEntity("Name")]`	`partial struct`	Marks a struct as an entity kind. Accepts optional `EventStream = true` for per-assert events and `DiskBacked = true` for disk-backed storage.
`[ConvergenceStruct]`	`partial struct`	Marks a struct as an embeddable sub-struct.
`[Field(ordinal)]`	property	Assigns a stable field ordinal.
`[Field(ordinal, MaxLength = N)]`	`string` / `byte[]` property	Field with maximum byte length. Strings default to VarString; bytes default to VarBytes.
`[Field(ordinal, MaxLength = N, FixedLength = true)]`	`string` / `byte[]` property	Fixed-length inline storage (String/Bytes).
`[Field(ordinal, MaxCount = N)]`	array property	Field with maximum element count.

ConvergenceEntityAttribute properties

Property	Type	Default	Description
`Name`	`string`	(required)	The kind name registered with the server.
`EventStream`	`bool`	`false`	When true, the server records per-assert events for this kind.
`DiskBacked`	`bool`	`false`	When true, entities are stored on disk with an LRU cache instead of entirely in memory. Best for kinds with large populations and small hot working sets. See Defining Entity Kinds.
`CacheCapacity`	`uint`	`512`	Per-partition LRU cache floor when `DiskBacked = true`. The cache grows adaptively if the hit rate drops below 70% but never shrinks below this value. Each partition allocates its own cache, so total cache memory scales as `CacheCapacity × partition_count` per kind. Ignored when `DiskBacked` is false.

FieldAttribute properties

Property	Type	Default	Description
`Order`	`int`	(required)	Stable field ordinal. Determines wire layout position.
`MaxLength`	`int`	0	Maximum byte length for string and byte[] fields. Required for variable-length types.
`MaxCount`	`int`	0	Maximum element count for array fields (1 to 1024).
`Indexed`	`bool`	`false`	Reserved for future secondary index support.
`FixedLength`	`bool`	`false`	When true, uses fixed-length inline storage (String/Bytes) instead of the default variable-length storage (VarString/VarBytes).

ConvergeDbConnection

Built-in entity type for the convergedb_connections system kind. Available via client.Connections. See Client Presence.

Property	Type	Description
`EntityId`	`ReadOnlyMemory<byte>`	32-byte entity ID. Byte 0 is the source ID, bytes 1-31 are zero.
`Name`	`string`	Human-readable name from `ConvergenceOptions.Name`. Empty if not set.
`LastSeenAt`	`DateTimeOffset`	UTC timestamp of the most recent heartbeat or connect.

EntityId helpers

Method	Returns	Description
`EntityId.FromGuid(Guid)`	`ReadOnlyMemory<byte>`	32 bytes from a GUID.
`EntityId.FromLong(long)`	`ReadOnlyMemory<byte>`	32 bytes from a long.
`EntityId.FromULong(ulong)`	`ReadOnlyMemory<byte>`	32 bytes from a ulong.
`EntityId.FromString(string)`	`ReadOnlyMemory<byte>`	32 bytes via SHA-256.
`EntityId.ToGuid(ReadOnlyMemory<byte>)`	`Guid`	Extract GUID from entity ID.
`EntityId.ToLong(ReadOnlyMemory<byte>)`	`long`	Extract long from entity ID.