Keep clients complete and unsurprising.

Orbita’s current server-side routing means a complete client can connect to one endpoint. Generated protobuf and gRPC types should remain visible rather than being hidden behind an abstraction that changes the contract.

Pin the wire contract

Generate from a specific Orbita commit or release. Before 1.0, protocol compatibility follows minor versions and should not be inferred from a mutable branch.

Discover limits

Call GetLimits before sending data. Many gRPC implementations default to 4 MB messages; Orbita can be configured above that, and a client that does not adjust its channel limit fails inside gRPC rather than with an Orbita error.

Do not retry mutations blindly

Read-only UNAVAILABLE calls can be retried. A failed mutation reply is ambiguous because the write may have committed. Return an explicit ambiguous-mutation error and require reconciliation with a linearizable read.

Preserve conditions

A failed compare-and-swap is a successful RPC with applied=false, not a transport error. Versions are opaque compare-and-swap tokens, not timestamps or per-key counters.

Preserve list semantics

Cursors are opaque. One page is a consistent partition snapshot; a multi-page scan is not a point-in-time snapshot of the entire keyspace.

Keep missing values distinct

Get reports found=false for a missing key. A gRPC NOT_FOUND error means the keyspace does not exist.

The source contract is proto/orbita/v1.