Skip to content

vox-runtime API Reference (generated)

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

Umbrella runtime crate for Vox — declares the RuntimeProfile (Desktop vs Mobile) + lifecycle traits + VoxConfig that downstream runtime crates (vox-workflow-runtime, vox-actor-runtime) and the uniffi-bindgen-react-native bridge consume. Foundation for @vox/runtime-rn on device.

Vox runtime — the umbrella crate that downstream runtimes (vox-workflow-runtime, vox-actor-runtime, vox-populi::inference) compose into a single mobile-and-desktop-aware surface.

This crate ships the foundational types the rest of the runtime layer will hang off:

  • [RuntimeProfile] — Desktop vs Mobile dispatch axis. Every scheduling, journaling, and ML-loading choice flows from this single enum.
  • [VoxConfig] — typed configuration carried at runtime construction (data dir, model dir, log level, profile).
  • [Suspendable] — lifecycle trait every actor / workflow / inference subsystem implements to participate in iOS applicationWillResignActive / Android onPause flows without losing state.
  • [JournalFlushStrategy] and [ModelLoadingStrategy] — typed descriptions of what each profile does differently, exported so callers (Tauri desktop shell, uniffi-bindgen-react-native Expo Module) can inspect the policy without re-deriving it.
  • It does not yet own the workflow / actor / inference loops. Those live in their respective crates and will adopt the [Suspendable] trait + take a [VoxConfig] in a follow-up commit per the implementation spec (Phase 2).
  • It does not expose a uniffi UDL surface yet. The mobile_rn_expo_implementation_spec_2026 §11 UDL hangs off the types declared here once the underlying runtimes adopt them.
DependencyKind
vox-configNormal
ModuleDescription
config—
lifecycle—
profile—
Dependency Topology, diagram 15 nodes, 4 edges: vox-runtime → vox-config; vox-journal → vox-runtime; vox-runtime-rn → vox-runtime; vox-workflow-runtime → vox-runtimevox-runtimevox-configvox-journalvox-runtime-rnvox-workflow-runtime
Diagram source
graph {
direction: right
node vox_runtime: "vox-runtime"
node vox_config: "vox-config"
vox_runtime -> vox_config
node vox_journal: "vox-journal"
vox_journal -> vox_runtime
node vox_runtime_rn: "vox-runtime-rn"
vox_runtime_rn -> vox_runtime
node vox_workflow_runtime: "vox-workflow-runtime"
vox_workflow_runtime -> vox_runtime
}
Consumer CrateRole
vox-journalDirect workspace dependent
vox-runtime-rnDirect workspace dependent
vox-workflow-runtimeDirect workspace dependent
KindSymbolSignatureSourceDescription
structconfig::VoxConfigpub struct VoxConfigcrates/vox-runtime/src/config.rs#L17-L38Top-level configuration for a Vox runtime instance.
fnconfig::desktoppub fn desktop() -> Selfcrates/vox-runtime/src/config.rs#L45-L53Build a desktop-profile config with sensible defaults. Both directories live under ~/.vox/default/ unless overridden via the returned config’s mutable fields.
fnconfig::mobilepub fn mobile(data_dir: PathBuf) -> Selfcrates/vox-runtime/src/config.rs#L60-L69Build a mobile-profile config rooted under data_dir. data_dir is the platform’s app-private documents directory; the runtime creates data_dir/data/ and data_dir/models/ subdirs as needed at startup. Log level defaults to info.
fnconfig::log_level_parsedpub fn log_level_parsed(&self) -> tracing::Levelcrates/vox-runtime/src/config.rs#L75-L84Parse [Self::log_level] into a typed [tracing::Level]. Returns tracing::Level::INFO when the stored string is unrecognized (logging a runtime warning is the caller’s responsibility).
enumlifecycle::SuspendDeadlinepub enum SuspendDeadlinecrates/vox-runtime/src/lifecycle.rs#L36-L47How long a suspendable subsystem has to complete its suspend() call. Strict deadlines force the runtime to abandon any subsystem that hasn’t returned in time; Advisory deadlines log a warning and continue waiting (used in tests + on desktop where the OS isn’t about to kill us).
fnlifecycle::mobile_defaultpub fn mobile_default() -> Selfcrates/vox-runtime/src/lifecycle.rs#L51-L55Default strict deadline for mobile profiles.
fnlifecycle::desktop_defaultpub fn desktop_default() -> Selfcrates/vox-runtime/src/lifecycle.rs#L58-L62Default advisory deadline for desktop profiles.
fnlifecycle::durationpub fn duration(self) -> Durationcrates/vox-runtime/src/lifecycle.rs#L65-L69Get the inner [Duration] regardless of variant.
enumlifecycle::SuspendErrorpub enum SuspendErrorcrates/vox-runtime/src/lifecycle.rs#L74-L90Error raised by a subsystem’s suspend() implementation.
enumlifecycle::ResumeErrorpub enum ResumeErrorcrates/vox-runtime/src/lifecycle.rs#L94-L104Error raised by a subsystem’s resume() implementation.
traitlifecycle::Suspendablepub trait Suspendablecrates/vox-runtime/src/lifecycle.rs#L114-L120A subsystem that can be suspended in response to an OS lifecycle event. Implementors are expected to: 1. Flush any in-memory state to durable storage (journal, snapshot, etc.). 2. Cancel any background tasks that hold non-snapshottable handles. 3. Return promptly — the runtime calls every subsystem’s suspend() in sequence, and the OS grace period is shared across all of them.
traitlifecycle::Resumablepub trait Resumablecrates/vox-runtime/src/lifecycle.rs#L127-L130A subsystem that can resume after a prior suspend. Resume is the inverse of [Suspendable::suspend]: the runtime calls resume() once the app returns to the foreground, and the implementor replays the journal / re-mounts handles / restarts background tasks.
enumprofile::RuntimeProfilepub enum RuntimeProfilecrates/vox-runtime/src/profile.rs#L19-L28Where this Vox runtime is executing. Drives every per-target choice in the runtime layer. The default is [RuntimeProfile::Desktop] because that’s the lower-friction value for development hosts; a Vox app that ships to mobile constructs its VoxConfig with [RuntimeProfile::Mobile] explicitly.
fnprofile::default_scheduler_threadspub fn default_scheduler_threads(self) -> SchedulerThreadscrates/vox-runtime/src/profile.rs#L35-L40Default Tokio scheduler thread count for this profile. On desktop we let Tokio pick (its default is num_cpus); on mobile we pin to a single thread to honor battery + memory budgets.
fnprofile::journal_flush_strategypub fn journal_flush_strategy(self) -> JournalFlushStrategycrates/vox-runtime/src/profile.rs#L43-L50How the workflow journal should flush to disk.
fnprofile::model_loading_strategypub fn model_loading_strategy(self) -> ModelLoadingStrategycrates/vox-runtime/src/profile.rs#L53-L60How MENS / Candle ML models are kept in memory.
fnprofile::requires_suspend_hookspub fn requires_suspend_hooks(self) -> boolcrates/vox-runtime/src/profile.rs#L67-L69Whether subsystems on this profile should opt into the [Suspendable] lifecycle hooks. Desktop subsystems can ignore them; mobile must implement them or risk data loss when the OS suspends the app. [Suspendable]: crate::lifecycle::Suspendable
enumprofile::SchedulerThreadspub enum SchedulerThreadscrates/vox-runtime/src/profile.rs#L77-L86Tokio scheduler thread-count policy. Used by [RuntimeProfile::default_scheduler_threads].
enumprofile::JournalFlushStrategypub enum JournalFlushStrategycrates/vox-runtime/src/profile.rs#L91-L100Journal flush policy.
enumprofile::ModelLoadingStrategypub enum ModelLoadingStrategycrates/vox-runtime/src/profile.rs#L105-L115ML model loading + retention policy.