Mission SDKErrors, security, and compatibility

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

ConditionIntegration response
Local entity save failsDo not announce a successfully saved Track. Preserve input under your adapter's retention policy and expose the error.
Save succeeds, advertisement failsRetain the Track reference. Report live telemetry unavailable. A detection can omit stream_ref.
Event accepted locally, no delivery observedReport local acceptance only. Do not erase the Track or claim a remote acknowledgement.
Detection arrives before entity statePresent a fresh bounded observation. Resolve asynchronously with a cancellation deadline.
Entity resolution remains pendingKeep pending distinct from denied and terminal absence. Do not fabricate state.
Event subscription deniedCorrect scope or obtain authority. Do not resubscribe to a broader topic.
Telemetry denied or revokedClose the affected subscription and expose denied state. An event reference grants no exception.
Descriptor expires or producer restartsDiscover the current descriptor and verify producer identity before reopening.
Consumer capacity is fullReject or replace work by explicit application policy. Report capacity rather than grow an unbounded queue.
Refresh fails after a local commitRe-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 boundaryMeaningResponse
ATLAS-SDK-002Native application facade is not initializedCorrect the host-provided facade context. Do not initialize another runtime from a worker.
ATLAS-SDK-001Native application facade is already initializedReuse its host lifecycle owner rather than initialize twice.
ATLAS-SDK-SHUTDOWN-001Native facade cleanup failedRecord the failure and follow the host's lifecycle recovery before reopening.
ATLAS-ORG-005Organization departure violates the sole-administrator ruleArrange valid successor authority. force does not bypass the invariant.
ATLAS-VALIDATION-001Input validation failsCorrect input before retrying.
RustLib.init() content-hash mismatchDart bindings and native library differRebuild 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.