Runtime FFI Surface

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.
ABI version — synheart_core_build_info reports the C ABI as MAJOR.MINOR. A new MINOR only adds symbols; a new MAJOR removes or re-signs some, so an SDK built for one MAJOR refuses the others. Runtime 0.42 is ABI 4.0, 0.43 is 4.1 (HSM Schema consent) and 0.45 is 4.2 (the daily score inputs changed shape). Flutter synheart_core 0.22 and later and Kotlin and Swift 0.6 and later require ABI 4.2 (runtime 0.45.0 or later).

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

Signatures below were introduced in ABI 4.0 (runtime 0.42) and are unchanged through ABI 4.2. ts_ms is Unix epoch milliseconds. provider names the source ("ble_hrm", "sdk_wear", …; NULL uses the default). utc_offset_min is the person’s offset from UTC at the sample, in minutes (±840), so samples land on the right local day across a daylight-saving change or a flight.

Symbol	Purpose
`synheart_core_push_hr(handle, ts_ms, bpm, provider, utc_offset_min)`	Heart-rate sample.
`synheart_core_push_rr(handle, ts_ms, rr_ms, provider, utc_offset_min)`	RR-interval sample (beat to beat). The highest-fidelity input.
`synheart_core_push_rr_batch(handle, anchor_ts_ms, rr, len, order, provider, utc_offset_min)`	Several RR intervals that arrived together, such as one BLE notification.
`synheart_core_push_accel(handle, ts_ms, x, y, z, provider, utc_offset_min)`	Phone accelerometer sample, in g.
`synheart_core_push_behavior(handle, ts_ms, event_type, value)`	Behavior event (tap, scroll, swipe, app switch, …) by numeric type.
`synheart_core_push_sleep_stages(handle, stages_json)`	Sleep stages from a wearable.
`synheart_core_ingest_batch(handle, batch_json, now_ms) -> *char`	Several samples in one call; each event may carry `utc_offset_min`. Returns an HSI document when a window completed, else `NULL`.
`synheart_core_push_inputs_json(handle, inputs_json) -> *char`	A typed batch (samples, presses, scrolls, notifications, day types, daily values). Returns what went in and why the rest did not.

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.

See Cloud Protocol for the wire shape.

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).

See Consent System and Capability System for the model.

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 maintains longitudinal baselines per subject.

Symbol	Purpose
`synheart_core_srm_push_wearable_daily(handle, provider, metric, year, month, day, value, vendor_summary) -> int`	One daily value for one local date. `0` stored, `1004` refused, `5002` out of bounds or not permitted, `-1` no pipeline: call `synheart_core_ensure_pipeline(handle)` first when no session is running. See daily metrics.
`synheart_core_srm_refresh_wearable_reference(handle, year, month, day) -> int`	Rebuild the wearable reference from the dates before the given date. Call with today after a batch of daily values.
`synheart_core_daily_baseline_refs_json(handle)`	The Recovery and Readiness baselines as JSON, read after a refresh (ABI 4.2).
`synheart_core_daily_sleep_baselines_json(handle)`	The Sleep Score’s baselines as JSON, read after a refresh (ABI 4.2).
`synheart_core_export_baseline_snapshot(handle) -> *char`	Every personal baseline as opaque base64. Only for a host that persists outside the runtime’s data directory.
`synheart_core_load_baseline_snapshot(handle, snapshot_b64) -> int`	Restore that snapshot. A snapshot from a runtime before 0.42 is refused, and the baselines start fresh.
`synheart_core_attach_closed_day_strain_json(handle) -> *char`	Score the local day the engine closed last and attach it to the next frame.
`synheart_core_set_input_capture(handle, running, ts_ms) -> int`	Report whether input capture is running, which decides when a still window counts as rest.
`synheart_core_baselines_json(handle) -> *char`	Current per-dimension baselines (mean / std / sample count).
`synheart_core_srm_overall_status(handle) -> *char`	`{"status": "empty" \| "warming" \| "ready"}`. A stale baseline reports `warming`. See maturity states.

9. Sync

Symbol	Purpose
`synheart_core_set_sync_enabled(handle, enabled)`	Build (`1`) or dispose (`0`) the sync engine. Disabling keeps the space membership.
`synheart_core_sync_readiness(handle) -> *char`	Prerequisite booleans plus the first unmet gate as `state`: `CONFIGURATION_MISSING`, `STORAGE_UNAVAILABLE`, `DEVICE_REVOKED`, `DEVICE_REGISTRATION_REQUIRED`, `ENGINE_NOT_INITIALIZED`, `NO_ACTIVE_SPACE`, `SRK_UNAVAILABLE`, or `READY`.
`synheart_core_sync_create_space(handle, device_name) -> *char`	Create a space. Returns `{sync_space_id, recovery_key}`. `device_name` may be NULL.
`synheart_core_sync_generate_pairing(handle) -> *char`	Issue a single-use pairing token. Returns `{token, expires_in}`.
`synheart_core_sync_pairing_status(handle, token) -> *char`	Poll a pairing token. Returns `{status, sync_space_id, joined_device, joined_at, expires_at}`; `status` is `waiting`, `joined`, `expired`, or `unknown`.
`synheart_core_sync_join_space(handle, pairing_token, device_name) -> *char`	Join with a pairing token. Returns `{sync_space_id, status}`.
`synheart_core_sync_recover_space(handle, recovery_key, space_id) -> *char`	Rejoin with the recovery key. Returns `{sync_space_id, owner_user_id, status}`.
`synheart_core_sync_now(handle) -> *char`	Run one push and pull cycle. Returns `{pushed, pulled, conflicts_resolved, errors}`. Blocks on network I/O.
`synheart_core_sync_list_devices(handle) -> *char`	Returns `{devices: [{device_id, device_name, is_primary, trusted_at, last_seen_at, revoked}]}`.
`synheart_core_sync_revoke_device(handle, device_id) -> *char`	Remove another device from the space.
`synheart_core_sync_leave_space(handle) -> *char`	Remove this device from the space, then clear local state.
`synheart_core_sync_delete_space(handle) -> *char`	Delete the space for every device. Owner only.
`synheart_core_sync_clear_local_space(handle) -> *char`	Clear local space state without a network call.
`synheart_core_sync_status(handle) -> *char`	Returns `{enabled}`: whether the sync engine is built.

Every function except set_sync_enabled returns a JSON envelope: {"ok": true, "data": {...}} on success, or {"ok": false, "error": {code, message, retryable, owner, recovery, ...}} on failure. Free the string with synheart_core_free_string. See Cross-device sync for the flow and error codes.

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.

Forgetting to call this on returned strings leaks memory. SDK shells handle it automatically; custom integrations must call it themselves.

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.
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 against the relevant SDK repo at github.com/synheart-ai.

Architecture — how the SDK composes around the FFI.
Cloud Protocol — what HSI windows look like on the wire.
HSV Specification — the typed inference output the runtime emits.
HSI Specification — the public wire format.

Get Started

Security

Setup

CLI

Synapse

Platform

HSI

Synheart Wear

Synheart Auth

Synheart Core

Synheart Behavior

Syni

Syni Spec

Synheart Session

RAMEN 🍜

Lab Mode

Privacy

Guides

When you’d care

ABI rules

1. Handle and lifecycle

2. Session lifecycle

3. HSI streaming

4. Sample ingest

5. Cloud upload

7. Sessions and local storage

8. SRM and baselines

9. Sync

10. Account deletion

11. Multi-source priority resolver

12. Stateless score computation

13. Apple Health backfill

14. Diagnostics

15. Memory management

Symbols this page does not document

When you’d care

ABI rules

1. Handle and lifecycle

2. Session lifecycle

3. HSI streaming

4. Sample ingest

5. Cloud upload

6. Consent and capability

7. Sessions and local storage

8. SRM and baselines

9. Sync

10. Account deletion

11. Multi-source priority resolver

12. Stateless score computation

13. Apple Health backfill

14. Diagnostics

15. Memory management

Symbols this page does not document

Related