Consent result states
Section titled “Consent result states”| State | SDK instance | Retry behavior |
|---|---|---|
accepted | Present | Connect once and wait for online |
declined | Absent | Respect decision; no prompt loop |
revoked | Absent | Remain disabled for current scope |
cancelled | Absent | Allow deliberate future retry |
error | Absent | Correct configuration or show support path |
Connection phases
Section titled “Connection phases”The native runtime can move through:
Idle: no supervisor running.Discovering: runtime onboarding is in progress.ConnectingTransport: authentication and transport setup are in progress.Online: owner connection is active.Backoff: waiting before a policy-driven retry.BatteryPaused: paused by battery policy.Disconnecting: shutdown requested.Closed: terminal; cannot reconnect.
Most wrappers expose connected/disconnected events and isOnline, not every internal phase.
Disconnect reasons
Section titled “Disconnect reasons”| Reason | Meaning | Application response |
|---|---|---|
Manual | Application requested disconnect | Update state; no error UI required |
Network | Connectivity failed | Show offline if relevant; allow SDK policy to retry |
ServerUnavailable | Service unavailable | Record sanitized event; avoid tight retry loop |
TokenExpired | Runtime session requires refresh | SDK can perform a new connection attempt |
LowBattery | Assigned policy paused participation | Respect policy; do not override |
DiscoveryError | Control-plane setup failed | Check API key, consent state, time, and network |
ProtocolError | Incompatible or invalid exchange | Verify package versions and contact support |
Unknown | Unrecognized or unmapped reason | Preserve numeric/raw category for support without secrets |
Structured error fields
Section titled “Structured error fields”Native ABI provides error code, retryability, disconnect reason, and a short message. Managed wrappers map these into typed errors where possible.
Unknown positive native error codes must become generic SDK failures, not success. Unknown disconnect values must map to Unknown so applications remain forward-compatible.
Retry guidance
Section titled “Retry guidance”Retryable does not mean “retry immediately from application code.” The supervisor owns connection retry. Application-level retry is appropriate for explicit creation, package/configuration correction, or a failed user revoke after showing feedback.
Last-error lifetime
Section titled “Last-error lifetime”The C ABI last-error message is thread-local and temporary. Read and copy it immediately after a failed native call before any other SDK call on that thread.