Documentation Index
Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt
Use this file to discover all available pages before exploring further.
The Synheart SDKs (Dart, Swift, Kotlin) are thin shells over a native runtime binary. They communicate across a stable C ABI that is loaded at startup via dlsym (Apple platforms / Linux) or JNI (Android). This page documents the symbols your SDK actually calls.
Most apps never touch this layer directly — the SDK wraps it. This page is for: build-error diagnosis, custom integrations (CLIs, embedded hosts), or auditing what the SDK does on your behalf.
When you’d care
You see one of these:
- A linker error mentioning
libsynheart_core_runtime or undefined synheart_core_* symbols.
- A
dlsym / JNI error at runtime.
- You’re embedding the runtime directly without using the SDK shells.
- You’re writing platform glue code that calls the runtime from a non-mainstream language.
If none of these apply, Architecture is the page you want.
ABI rules
- C calling convention —
extern "C", no name mangling, no exceptions across the boundary.
- Handle ownership —
synheart_core_new returns an opaque *const SynheartCore handle that the SDK owns and must free with synheart_core_free.
- Strings out of the runtime are heap-allocated
*char (UTF-8, null-terminated). Caller must release with synheart_core_free_string. Returning NULL means “no value” (not an error — check last_error_code).
- Strings into the runtime are borrowed for the duration of the call. The runtime copies what it needs.
- Structured returns are JSON strings. Lenient JSON parsing on both sides — unknown fields are tolerated.
- Error codes are negative integers; success is
0 or a positive value (e.g. queue length).
- Thread safety — the runtime is internally synchronised. Any thread can call any function on a handle. Callbacks (HSI, log, stream) fire on a runtime-owned thread; the SDK shell is responsible for re-dispatching to the host’s UI/main thread.
1. Handle and lifecycle
| Symbol | Purpose |
|---|
synheart_core_new(config_json) -> *const SynheartCore | Construct a runtime handle from a JSON config (subject id, data dir, cloud config, retention, etc.). |
synheart_core_free(handle) | Destroy the handle. Idempotent on NULL. |
synheart_core_is_runtime_available() -> bool | Returns true if the loaded shared library is the runtime. SDKs call this on startup to verify the binary is linked. |
synheart_core_last_error_code(handle) -> int32_t | Negative integer for the most recent error. Reset to 0 after read. |
2. Session lifecycle
| Symbol | Purpose |
|---|
synheart_core_start_session(handle, session_kind, metadata_json) -> *char | Open a session. Returns the session id as a JSON string ({"session_id": "..."}) or NULL on failure. |
synheart_core_stop_session(handle, session_id) -> int | Close a session. Returns 0 on success. |
synheart_core_current_session(handle) -> *char | Currently open session JSON, or NULL if no session is active. |
synheart_core_is_running(handle) -> bool | Convenience flag — true when the engine pipeline is running. |
3. HSI streaming
The runtime emits HSI 1.3 windows on a configurable cadence (default: 60s window, 5s step). Hosts subscribe via callback; the SDK exposes the stream as Stream<HSIState> / AnyPublisher<...> / Flow<...>.
| Symbol | Purpose |
|---|
synheart_core_set_hsi_callback(handle, callback, user_data) | Register a callback (user_data, json_ptr, json_len) -> void invoked once per emitted HSI window. |
synheart_core_clear_hsi_callback(handle) | Unregister the callback. Called during SDK teardown. |
synheart_core_get_hsi_windows(handle, since_ms, limit) -> *char | Replay recent HSI windows from local storage (JSON array). |
synheart_core_enqueue_hsi(handle, hsi_json) -> int | Enqueue an HSI window for cloud upload. Used when the SDK has the JSON in hand and wants to skip the listener. |
4. Sample ingest
The runtime accepts sensor samples through five push functions. All ts_ms parameters are device monotonic milliseconds.
| Symbol | Purpose |
|---|
synheart_core_push_hr(handle, ts_ms, bpm, source) -> int | Heart-rate sample. source is a string id ("apple_healthkit", "ble_hrm", etc.). |
synheart_core_push_rr(handle, ts_ms, rr_ms, source) -> int | RR-interval sample (raw beat-to-beat). Highest fidelity input. |
synheart_core_push_accel(handle, ts_ms, x, y, z) -> int | Accelerometer sample (m/s²). Drives motion-state head. |
synheart_core_push_behavior(handle, ts_ms, event_type, payload_json) -> int | Behavior event (tap, scroll, swipe, app_switch, …). Payload is content-free metadata. |
synheart_core_push_sleep_stages(handle, stages_json) -> int | Per-window sleep stages (REM/NREM/wake/awake) from a wearable. |
synheart_core_ingest_batch(handle, samples_json) -> int | Bulk-ingest multiple samples in one call. Used during catch-up after backgrounding. |
5. Cloud upload
The runtime owns a persistent SQLite upload queue. The SDK observes it; the runtime drains it.
| Symbol | Purpose |
|---|
synheart_core_flush_uploads(handle) -> *char | Force-flush the queue if eligible (consent + reachability). Returns a JSON result {"uploaded": n, "failed": n, "requeued": n}. |
synheart_core_upload_queue_length(handle) -> int32_t | Current queue depth. |
synheart_core_last_ingest_success_at_ms(handle) -> int64_t | Epoch-ms of the last successful upload, or 0 if never. |
synheart_core_is_network_reachable(handle) -> bool | Cached reachability flag (the runtime monitors <api_base>/health). |
synheart_core_upload_metadata(handle) -> *char | Diagnostic JSON: queue depth, last error, last attempt, backoff state. |
6. Consent and capability
| Symbol | Purpose |
|---|
synheart_core_grant_consent(handle, snapshot_json) -> int | Grant consent for one or more types. Snapshot JSON has boolean fields per consent type. |
synheart_core_revoke_consent(handle, type_or_null) -> int | Revoke a single consent type, or all if type_or_null is NULL. |
synheart_core_has_consent(handle, consent_type) -> int | 1 if granted, 0 if denied, negative on error. |
synheart_core_current_consent(handle) -> *char | Full consent snapshot as JSON. |
synheart_core_load_capability_token(handle, token_jwt) -> int | Install a capability token. The token determines which features the SDK can activate (core / extended / research). |
7. Sessions and local storage
The runtime owns local persistence (SQLite plus encrypted preference storage on Apple/Android).
| Symbol | Purpose |
|---|
synheart_core_list_sessions(handle, since_ms, limit) -> *char | JSON array of historical session metadata. |
synheart_core_get_session_summary(handle, session_id) -> *char | Per-session aggregate (HR mean/std, HRV, duration, etc.). |
synheart_core_delete_session(handle, session_id) -> int | Delete one session and its windows. |
synheart_core_wipe_local_data(handle) -> int | Clear all local stores: queue, history, sessions, HSI windows, SRM snapshot. Does not affect cloud data. |
synheart_core_set_retention_days(handle, days) -> int | Configure rolling-window retention for HSI history. |
synheart_core_get_storage_usage(handle) -> *char | JSON breakdown of bytes used per store. |
synheart_core_record_metric(handle, name, value_json) -> int | Append an app-defined metric to the active session. |
8. SRM and baselines
The Self-Reference Model (SRM) maintains longitudinal baselines per subject.
| Symbol | Purpose |
|---|
synheart_core_export_srm_snapshot(handle) -> *char | Serialise the current SRM snapshot as JSON. Hosts persist this through their own secure store. |
synheart_core_load_srm_snapshot(handle, snapshot_json) -> int | Restore a snapshot on cold start. |
synheart_core_baselines_json(handle) -> *char | Current per-modality baselines (mean / std / sample count). |
synheart_core_wellness_json(handle) -> *char | Wellness derivatives (recovery, strain, readiness inputs) keyed by date. |
synheart_core_srm_overall_status(handle) -> *char | Overall maturity status of the SRM (e.g. bootstrap, active). |
9. Sync
| Symbol | Purpose |
|---|
synheart_core_sync_now(handle) -> *char | Trigger an immediate device-first sync cycle. Returns a JSON result. |
synheart_core_set_sync_enabled(handle, enabled) -> int | Enable or disable the background sync layer. |
10. Account deletion
| Symbol | Purpose |
|---|
synheart_core_request_account_deletion(handle) -> *char | Enter wind-down mode and signal the platform to delete cloud data. Returns a DeletionRequestResult JSON. |
synheart_core_cancel_account_deletion(handle) -> *char | Undo the deletion request before the platform confirms. |
11. Multi-source priority resolver
When multiple wearables / vendors push the same metric, the runtime de-duplicates via a priority resolver. SDKs configure it so the SDK consumer’s source preferences flow into the runtime gate.
| Symbol | Purpose |
|---|
synheart_core_priority_set_provider(handle, metric, provider, rank) -> int | Assign a priority rank for a given metric/provider pair. Lower rank wins. |
synheart_core_priority_set_metric_override(handle, metric, provider) -> int | Force a specific provider to win for a metric, regardless of rank. |
synheart_core_priority_resolve(handle, metric) -> *char | Resolve which provider currently owns this metric. |
synheart_core_priority_effective_rank(handle, metric, provider) -> int | Effective rank after override / fallback rules. |
12. Stateless score computation
These are stateless utility calls — they don’t read or mutate the handle’s state, just compute a result from the input JSON. The _handle parameter is unused; pass NULL.
| Symbol | Purpose |
|---|
synheart_core_recovery_score_compute_json(_, input_json) -> *char | Daily 0–100 recovery score from sleep + overnight HR/HRV. |
synheart_core_readiness_score_compute_json(_, input_json) -> *char | Daily 0–100 readiness score combining recovery, workload, and trend signals. |
synheart_core_resilience_compute_v1(samples_json, windows_json, config_json) -> *char | HRV-CV resilience score over a multi-day window. |
13. Apple Health backfill
When a user exports export.zip from the iOS Health app, the SDK feeds it back into the runtime via this batch path. Idempotency keys ensure repeated imports don’t duplicate samples.
| Symbol | Purpose |
|---|
synheart_core_backfill_open(handle, db_path, import_id) -> int | Open a backfill session. |
synheart_core_backfill_insert_batch(handle, import_id, samples_json) -> int | Insert a batch of samples. |
synheart_core_backfill_finalize(handle, import_id) -> int | Commit and aggregate the import; updates SRM baselines. |
14. Diagnostics
| Symbol | Purpose |
|---|
synheart_core_diagnostics(handle) -> *char | JSON dump of runtime state: availability, version, frame count, last quality, queue stats, last error. The SDK exposes this as Synheart.runtimeDiagnostics(). |
15. Memory management
| Symbol | Purpose |
|---|
synheart_core_free_string(ptr) | Release a *char returned by any of the calls above. Calling on NULL is a no-op. |
Symbols this page does not document
The runtime exports more than what’s listed here. Those undocumented symbols are either:
- Tracing variants (
*_traced with a correlation id parameter) — useful for runtime debugging only.
- Lab / research tier (
synheart_core_lab_*) — gated by the research capability and not part of the stable public surface.
- Personalization (focus / task / workout context APIs) — currently only used by the Dart SDK and not yet stabilised.
- Vendor event ingestion (
*_vendor_*) — internal to the cloud connector seam.
- Internal counters (
frame_count, last_features, last_quality) — diagnostic-only, may change.
Treat anything not on this page as unstable. If you find yourself needing one of these, file an issue at feedback.synheart.ai.
