Errors, security, and compatibility
Handle Mission failures without losing local commits or widening authority.
Recover the failed data path without undoing successful local work or widening authority. Check the saved entity, event acceptance, observed delivery, and telemetry subscription as separate outcomes.
Platform offline behavior and errors defines generic recovery. Platform compatibility defines shared format and version rules. Use the Mission decisions below for domain authority, binding errors, and component matching.
Failure decisions
| Condition | Integration response |
|---|---|
| Local entity save fails | Do not announce a successfully saved Track. Preserve input under your adapter's retention policy and expose the error. |
| Save succeeds, advertisement fails | Retain the Track reference. Report live telemetry unavailable. A detection can omit stream_ref. |
| Event accepted locally, no delivery observed | Report local acceptance only. Do not erase the Track or claim a remote acknowledgement. |
| Detection arrives before entity state | Present a fresh bounded observation. Resolve asynchronously with a cancellation deadline. |
| Entity resolution remains pending | Keep pending distinct from denied and terminal absence. Do not fabricate state. |
| Event subscription denied | Correct scope or obtain authority. Do not resubscribe to a broader topic. |
| Telemetry denied or revoked | Close the affected subscription and expose denied state. An event reference grants no exception. |
| Descriptor expires or producer restarts | Discover the current descriptor and verify producer identity before reopening. |
| Consumer capacity is full | Reject or replace work by explicit application policy. Report capacity rather than grow an unbounded queue. |
| Refresh fails after a local commit | Re-read by the returned identifier. Do not blindly create the object again. |
Reconnect behavior comes from Platform events and Platform streams. A reconnect does not imply replay of every missed live notification or sample.
Typed Mission operations report the platform.ApiError contract through the Mission reference. Branch on its structured code. Only PendingState permits the consumer's bounded state-resolution retry. Authorization and schema failures do not retry.
Binding errors
The native facade's versioned Dart calls throw AtlasException. Branch on code or kind, not localized message. Observe retryable and any retry delay. Native Mission codes use the dashed ATLAS-<AREA>-<NNN> spelling. Platform codes use a separate upper-snake registry.
| Code or boundary | Meaning | Response |
|---|---|---|
ATLAS-SDK-002 | Native application facade is not initialized | Correct the host-provided facade context. Do not initialize another runtime from a worker. |
ATLAS-SDK-001 | Native application facade is already initialized | Reuse its host lifecycle owner rather than initialize twice. |
ATLAS-SDK-SHUTDOWN-001 | Native facade cleanup failed | Record the failure and follow the host's lifecycle recovery before reopening. |
ATLAS-ORG-005 | Organization departure violates the sole-administrator rule | Arrange valid successor authority. force does not bypass the invariant. |
ATLAS-VALIDATION-001 | Input validation fails | Correct input before retrying. |
RustLib.init() content-hash mismatch | Dart bindings and native library differ | Rebuild or obtain the matched pair. This is a StateError, not an Atlas error code. |
Check each operation's Mission reference for its full error set. These native codes do not define a numeric mapping for the typed session's event and stream errors.
Protect the integration
Persist keys and local storage encryption material through the host's protected key store. Keep account recovery and organization recovery separate. Never embed private keys in example configuration, logs, event observations, descriptors, or downloadable diagnostics.
Verify both account and device binding. Use the signed actor resolved by the SDK. A payload's created_by, producer label, or team identifier cannot choose the authenticated caller.
Authorize entity, event, and telemetry access separately. Treat Group-protected data, Gateway Fabric storage, adapter input, and external software output as explicit trust boundaries. A transport connection proves neither Group membership nor permission to write.
Revocation prevents further authorized work. It does not retroactively remove bytes from another peer's storage. Plan local retention, operator access, backups, and disposal accordingly.
Match component versions
Pin the Mission artifact, its exact Platform dependency, native target, feature profile, and Dart/native binding pair. Record the Gateway Fabric artifact version when the deployment uses it. Components have independent release trains.
Events and telemetry use versioned schema identifiers. Reject an incompatible major payload instead of decoding it as a known type. Keep old schema definitions available for saved documents and ontology references.
Contract editions document API behavior. Release editions identify immutable matching software artifacts. A method in one edition need not exist in another edition's package.
Diagnostic record
Keep the operation, scope identifiers, entity reference, event identifier, stream producer and session, outcome code, and observed time. Record local commit and delivery observations separately. Apply a bounded retention policy to raw sensor inputs and diagnostics.
Do not record keys, seeds, recovery phrases, invite secrets, or authorization tokens. Organization identifiers are ordinary scope identifiers, but event observations and coordinates can still need deployment-specific access controls.