vox-runtime-rn API Reference (generated)

vox-runtime-rn

Crate: vox-runtime-rn · Version: 0.6.0 · Target: Library (lib.rs)

uniffi-bridged Rust runtime for Vox mobile targets (React Native + Expo). Cross-compiles to aarch64-apple-ios / aarch64-linux-android / etc.; uniffi-bindgen-react-native generates the TypeScript TurboModule bindings that clients/runtime-rn/ consumes. Bridges the typed vox-runtime foundation types to JS.

Crate Overview

vox-runtime-rn — uniffi-bridged Vox runtime for React Native + Expo.

Re-exports the foundation types from [vox_runtime] through the uniffi proc-macro layer so uniffi-bindgen-react-native can generate the TypeScript TurboModule bindings that clients/runtime-rn/ consumes.

What’s exposed today

• [RuntimeProfile] mirror enum (uniffi can’t yet remote-import a type from another crate’s enum, so we wrap it via From impls).
• [VoxConfig] mirror record carrying the same fields as [vox_runtime::VoxConfig].
• [VoxRuntimeHandle] — the Rust-side runtime instance. Constructed from a [VoxConfig], exposes [VoxRuntimeHandle::profile], [VoxRuntimeHandle::data_dir], [VoxRuntimeHandle::model_dir], and [VoxRuntimeHandle::log] (which actually emits a tracing event).
• [VoxRnError] — typed errors raised by future fallible methods.

What’s NOT exposed yet (each will land with the underlying impl)

• spawn_actor / start_workflow — depend on vox-actor-runtime / vox-workflow-runtime adopting Suspendable and exposing a thread- safe public API. Tracked in spec §13.
• infer / transcribe — depend on Candle ML cross-compile + model-asset pipeline. Tracked in spec §15.

Until those land, the JS-side @vox/runtime-rn throws an explicit UnsupportedOnPlatform error for those methods. No silent stubs.

Workspace Dependencies

Dependency	Kind
vox-journal	Normal
vox-runtime	Normal

Public API Surface

Structs

Struct	Description
VoxConfig	Runtime configuration carried at construction (uniffi-exposed mirror of [vox_runtime::VoxConfig]). Fields are explicit String for the paths because uniffi doesn’t expose PathBuf across the FFI boundary; the strings are interpreted as paths inside the Rust side.
VoxRuntimeHandle	Live runtime instance, returned by [VoxRuntimeHandle::new]. Holds the parsed [InnerConfig] internally; mirror getters expose the fields back across uniffi without leaking PathBuf (which uniffi can’t transit).
JournalLine	A single JSON-encoded line carried by the file journal. The payload is opaque to the runtime — uniffi-exposed callers (JS side) pass arbitrary JSON strings; vox-journal handles append + replay + fsync. Letting the payload be a string instead of an opaque serde_json::Value is intentional: uniffi can’t transit Value directly across the FFI boundary, and the JS side already speaks JSON natively.
FileJournalHandle	Live file-journal handle exposed to JS. Construct via [open_file_journal]. Every successful append call fsyncs to disk before returning. replay_all returns every recorded line (in append order) as a list of JournalLines.

Enums

Enum	Description
RuntimeProfile	Runtime execution profile (uniffi-exposed mirror of [vox_runtime::RuntimeProfile]).
VoxRnError	Errors raised across the uniffi boundary.
FileJournalError	File journal errors raised across the uniffi boundary.

Functions

Function	Description
new	Construct a new runtime handle from the given configuration. Validates the config inline (parses log level via [InnerConfig::log_level_parsed]) so callers can’t construct a handle with a wildly invalid profile + log-level combo.
profile	The runtime’s [RuntimeProfile].
data_dir	The runtime’s data directory as a UTF-8 string.
model_dir	The runtime’s model directory as a UTF-8 string.
requires_suspend_hooks	Whether this profile requires the JS shell to wire suspend / resume lifecycle hooks (true on Mobile, false on Desktop).
log	Emit a tracing event from the JS side. The level string is interpreted the same way [InnerConfig::log_level_parsed] handles it — unknown values are silently coerced to info so this method never fails for a bad level argument.
default_desktop_config	Build a desktop-profile config with the platform’s default data + model directories. Equivalent to [vox_runtime::VoxConfig::desktop] but crosses the uniffi boundary so the JS side can request a sensible default without hardcoding host-specific paths.
default_mobile_config	Build a mobile-profile config rooted at data_dir. Counterpart of [vox_runtime::VoxConfig::mobile].
append	Append a JSON line. Returns an error if the line is not valid JSON or if the underlying I/O fails.
replay_all	Read every recorded line back into JS, in append order.
path	The on-disk path being written. Useful for tracing log lines on the JS side.
flush	Flush + fsync any in-flight bytes. This is the durability point for the mobile journal: appends run in [AppendDurability::Deferred] mode (no per-append fsync), so the JS lifecycle handler MUST call this from the OS suspend hook (app backgrounding) or un-synced appends can be lost on power-off. Idempotent and safe to call repeatedly. [AppendDurability::Deferred]: vox_journal::AppendDurability::Deferred
open_file_journal	Open (or create) a file journal at path. Returns a [FileJournalHandle] that the JS side can keep alive for the duration of the workflow. Opens in [AppendDurability::Deferred] mode — this is the mobile runtime bridge, so appends are batched (no per-call fsync, to honor battery + throughput budgets) and durability is taken at [FileJournalHandle::flush], which the JS side wires to the OS suspend hook. Replays any existing entries silently — the JS side calls [FileJournalHandle::replay_all] explicitly when it wants them. [AppendDurability::Deferred]: vox_journal::AppendDurability::Deferred