SynheartInstance class

A single, self-contained Synheart runtime instance (one native handle).

Synheart.shared is the personal runtime and remains the default surface for the app. Use SynheartInstance to run a second runtime alongside it — the canonical case being a research instance with its own pseudonymous subject_id, its own data_dir, and its own attested device identity, created on Life Lab enrol and disposed + wiped on withdraw.

The underlying CoreRuntimeBridge is already fully per-handle (every op is routed through its own native handle), so two instances are independent: distinct engines, Tokio runtimes, storage, and device-auth identities. The only hard requirement is a distinct dataDir and subject_id per instance — otherwise the two handles contend on the same SQLite / SRM files (see research-ingest-mobile.md §2.1–2.3).

Properties

config → SynheartConfig
final
dataDir → String
The durable directory this instance's native runtime writes to (synheart_<subject>.db, SRM snapshot, ingest queue). Must be unique per instance — e.g. <appSupport>/synheart-core/research.
final
deviceAuth → DeviceAuthProvider?
The per-instance device-auth provider (request signing), or null if device auth is unavailable for this instance.
no setter
hashCode → int
The hash code for this object.
no setterinherited
isDisposed → bool
no setter
isHsiBuffered → bool
Whether HSI reaches the listener by polling rather than by callback.
no setter
isLabAvailable → bool
Whether the lab C ABI is available in the loaded native build.
no setter
isLabMetadataAvailable → bool
Whether the lab-metadata C ABI is available in the loaded native build.
no setter
isLabReenqueueAvailable → bool
no setter
isSessionRunning → bool
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
subjectId → String?
The canonical subject id the runtime resolved (device-auth derives it from the client_id passed to registerDevice).
no setter
supportsRichBehaviorEvents → bool
Whether the loaded runtime takes rich behavior events on this instance. Same probe the static Synheart.supportsRichBehaviorEvents runs for the personal runtime. Both instances load one native library, but a host feeding two handles should ask the handle it is about to feed.
no setter

Methods

buildProofHeader(String method, String absoluteUrl) → String?
Build an X-Synheart-Proof header for an outbound request on this instance's identity.
clearHsiListener() → void
Stop HSI delivery. In buffered mode, frames still pending are delivered once more before the listener is dropped. Idempotent; dispose also clears it.
configId() → String?
This instance's comparability key. Persist it beside any cached score.
consentGetEditableForm() → Map<String, dynamic>?
consentStatus() → Map<String, dynamic>?
consentSubmitForm({required String deviceId, required String platform, String? userId, required Map<String, dynamic> formJson}) → Future<Map<String, dynamic>?>
declareRestWindow(int tsMs) → void
Declare the window containing tsMs to be a rest window. One-shot: call once per rest window, not once when a break begins.
deviceAuthStatus() → Map<String, dynamic>?
dispose() → void
Free the native handle. After this the instance is unusable. Idempotent.
drainHsi() → void
Deliver pending buffered frames to the listener now, oldest first, instead of waiting for the periodic drain. Cheap when nothing is pending; no-op without a listener or outside buffered mode.
enrolResearchStudy({required String accessCode, required String studyCode}) → Future<Map<String, dynamic>?>
Redeem an (access, study) code pair and create the enrolment on THIS instance's attested credential.
exportSessionState() → String?
Export this instance's per-head session state for persistence.
flushPending(int nowMs) → String?
Emit every window still held by the lateness budget. Call on backgrounding and at session end.
ingestBatch(String batchJson, int nowMs) → String?
labCloseWindow(String windowId, int endedAtMs) → bool
labEnsureMetadata({required String deviceId, required String platform, required String osVersion, String? userInfoJson, String? deviceExtraJson}) → String?
Ensure the lab-session metadata (device / platform / user info) is cached on this instance before the first labStart. Mirrors the personal runtime's labEnsureMetadata.
labFinalize(int endedAtMs) → String?
Finalize the lab session; the runtime auto-enqueues the payload to cloud lab-ingest under this instance's (research) identity.
labMergeSessionExtraData(String patchJson) → String?
labOpenWindow({String? parentId, required String windowType, String? label, required int startedAtMs}) → String?
labReenqueueSession(String sessionJson) → LabReenqueueResult
labSetWindowValues(String windowId, String valuesJson) → bool
labStart(String protocolJson, int startedAtMs) → String?
loadSessionState(String json) → int?
Restore session state. Must run before this instance's first tick.
logoutDevice() → Future<void>
Clear this instance's installed device identity and sync membership.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
pushAppForeground(String app, {int? tsMs}) → int?
Declare which application is in the foreground for THIS instance.
pushBehavior(int tsMs, int eventType, double value) → void
Push a raw behavior event into this instance's engine. Fed into an open lab session's behavioral metrics. eventType is a RuntimeBehaviorEvent code; most callers want pushBehaviorTouch.
pushBehaviorEvent(BehaviorEventInput event) → int?
Push a typed behavior event carrying its full payload — most importantly a windowed TypingSessionData, which the legacy int-coded path cannot express at all.
pushBehaviorTouch(int tsMs) → void
Push a touch/keystroke behavior event. During an open lab window this feeds the research lab session's typing dynamics so the finalized payload carries the same behavioral metrics the personal runtime produces.
pushContextEvent(ContextEventInput event) → int?
Push one privacy-preserving context event into this instance — the only source of context.deviation.*, and therefore of CFI. Mirrors the static Synheart.pushContextEvent; see it for the send-both-directions rule.
pushContextEventJson(Map<String, dynamic> event) → int?
Raw-payload escape hatch for pushContextEvent; the static Synheart.pushContextEventJson explains when to prefer the typed call.
pushHr(int tsMs, double bpm) → void
pushRr(int tsMs, double rrMs, {String provider = 'default_sensor'}) → void
Push an RR (inter-beat) interval into this instance. During an open lab window this feeds the research lab session's wear_data.
pushRrBatch(int anchorTsMs, List<double> rrMs, {int order = 0, String provider = 'default_sensor'}) → void
Push a batch of RR intervals delivered together in one sensor notification. See CoreRuntimeBridge.pushRrBatch. Prefer this over looping pushRr when a packet carries multiple RR values sharing one arrival timestamp (e.g. BLE HRM) — it keeps every beat.
reattestDevice() → Future<Map<String, dynamic>?>
Refresh this identity's attestation while preserving its device ID.
registerDevice(String clientId) → Future<Map<String, dynamic>?>
Register (attest) this instance's device identity under clientId. For a research instance, pass the pseudonymous research client id so the derived subject is research-scoped and unlinkable to the personal identity.
researchStudyStatus() → Future<Map<String, dynamic>?>
Read THIS instance's current active research-study enrolment.
setHsiListener(void onHsi(String hsiJson)) → void
Receive every HSI window this instance completes, as raw JSON — whether the host's tick or the runtime's background tick loop closed it.
startSession() → Map<String, dynamic>?
Start this instance's behavior/HSI session. Called before labStart so the engine has an active pipeline the lab window can record over (mirrors the personal runtime's startSession → labStart order).
stopSession() → bool
Stop this instance's session. Called after labFinalize.
syncReadiness() → Map<String, dynamic>?
Native device/Synsync readiness snapshot for THIS instance — the pollable signal used to detect a revoked or unregistered attested identity (device_revoked / device_registered).
tick(int nowMs) → String?
Advance the pipeline clock so windows that should close by nowMs are flushed (drives the same window-closing the personal runtime's ticker does).
tickAll(int nowMs) → String?
Drain every completed window as a JSON array, oldest first. Prefer this to tick after a gap. null when disposed or unsupported.
toString() → String
A string representation of this object.
inherited
validateResearchStudyCodes({required String accessCode, required String studyCode}) → Future<Map<String, dynamic>?>
Preview an (access, study) code pair for THIS instance without redeeming it.
wipeLocalData() → bool
Wipe this instance's local runtime data (SQLite, SRM, ingest queue, consent + device records). Call before dispose on study withdrawal.
withdrawResearchStudy() → Future<Map<String, dynamic>?>
Withdraw THIS instance from its active research study.

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Methods

create({required SynheartConfig config, required String dataDir}) → SynheartInstance?
Create and wire a new runtime instance, or null if the native library is unavailable / the handle could not be created.