Skip to content

vox-workflow-runtime API Reference (generated)

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

Interpreted workflow execution MVP (local + mens activity hooks)

Minimal interpreted workflow runner: walks a [vox_compiler::hir::HirModule] workflow body for activity calls and executes no-op steps with optional mens hooks.

  • Activities whose name starts with mesh_ are treated as [PopuliActivity] steps when the mens feature is enabled: they register with [vox_populi::publish_local_registry_best_effort] and run on the iroh mesh (never a user-supplied URL in workflow source). Use with { mens: "noop" | "join" | "snapshot" | "heartbeat" | "dispatch" | "wait" } to select the operation; see mesh_noop, mesh_join, mesh_snapshot shorthands.
  • Other activities are recorded as local no-ops (journal only).

Codex journal: unless VOX_WORKFLOW_JOURNAL_CODEX_OFF=1 disables it (and provided DB config resolves), vox-cli persists the interpreted journal after a successful run via VoxDb::record_workflow_journal_entry (see docs/src/architecture/orchestration-unified-ssot.md). Journal rows include ActivityStarted / ActivityCompleted with activity_id for idempotency hints and carry journal_version = 1 in emitted event objects.

This crate is the MVP engine behind vox mens workflow run when vox-cli is built with workflow-runtime.

FeatureDefault / Enables
defaultmens, sql
mensdep:vox-populi, vox-populi/transport, dep:vox-mesh-transport, dep:iroh
sqldep:vox-db
test-support—
DependencyKind
vox-compilerNormal
vox-configNormal
vox-dbNormal
vox-journalNormal
vox-mesh-transportNormal
vox-populiNormal
vox-runtimeNormal
vox-codegenDevelopment
vox-compilerDevelopment
ModuleDescription
db_trackerSQL-backed [workflow::WorkflowTracker] (requires the sql cargo feature).
durable_promiseDurablePromise<T> — the single awaitable primitive for distributed durable work (P1-T1).
duration_literalShared parser for @scheduled / workflow_wait duration literals (ADR-041 M-3, M-7).
file_journalAppend-only file-backed [workflow::WorkflowTracker] suitable for mobile + lightweight desktop.
scheduledPersistent @scheduled runner (Phase 4.2; requires the sql cargo feature).
workflow—
Dependency Topology, diagram 112 nodes, 11 edges: vox-workflow-runtime → vox-codegen; vox-workflow-runtime → vox-compiler; vox-workflow-runtime → vox-config; vox-workflow-runtime → vox-db; vox-workflow-runtime → vox-journal; vox-workflow-runtime → vox-mesh-transport; vox-workflow-runtime → vox-populi; vox-workflow-runtime → vox…vox-workflow-runtimevox-codegenvox-compilervox-configvox-dbvox-journalvox-mesh-transportvox-populivox-runtimevox-clivox-integration-testsvox-ml-cli
Diagram source
graph {
direction: right
node vox_workflow_runtime: "vox-workflow-runtime"
node vox_codegen: "vox-codegen"
vox_workflow_runtime -> vox_codegen
node vox_compiler: "vox-compiler"
vox_workflow_runtime -> vox_compiler
node vox_config: "vox-config"
vox_workflow_runtime -> vox_config
node vox_db: "vox-db"
vox_workflow_runtime -> vox_db
node vox_journal: "vox-journal"
vox_workflow_runtime -> vox_journal
node vox_mesh_transport: "vox-mesh-transport"
vox_workflow_runtime -> vox_mesh_transport
node vox_populi: "vox-populi"
vox_workflow_runtime -> vox_populi
node vox_runtime: "vox-runtime"
vox_workflow_runtime -> vox_runtime
node vox_cli: "vox-cli"
vox_cli -> vox_workflow_runtime
node vox_integration_tests: "vox-integration-tests"
vox_integration_tests -> vox_workflow_runtime
node vox_ml_cli: "vox-ml-cli"
vox_ml_cli -> vox_workflow_runtime
}
Consumer CrateRole
vox-cliDirect workspace dependent
vox-integration-testsDirect workspace dependent
vox-ml-cliDirect workspace dependent
KindSymbolSignatureSourceDescription
structdb_tracker::VoxDbTrackerpub struct VoxDbTrackercrates/vox-workflow-runtime/src/db_tracker.rs#L18-L24A durable workflow tracker that persists step completions to VoxDb.
fndb_tracker::newpub fn new(db: Arc<VoxDb>, run_id: impl Into<String>) -> Selfcrates/vox-workflow-runtime/src/db_tracker.rs#L28-L41Create a tracker for a specific workflow run.
fndb_tracker::with_ownerpub fn with_owner(crates/vox-workflow-runtime/src/db_tracker.rs#L44Create a tracker with explicit lease owner and TTL (tests and advanced runners).
fndb_tracker::with_plan_contextpub fn with_plan_context(crates/vox-workflow-runtime/src/db_tracker.rs#L60Attach optional orchestration planning context for this run tracker.
fndb_tracker::expire_lease_for_testpub async fn expire_lease_for_test(&self) -> anyhow::Result<()>crates/vox-workflow-runtime/src/db_tracker.rs#L76-L81Force the current run’s lease to become stealable by a resumed test runner.
enumdurable_promise::JournalErrorpub enum JournalErrorcrates/vox-workflow-runtime/src/durable_promise.rs#L23-L42Error variants for a durable activity execution.
structdurable_promise::DurablePromisepub struct DurablePromise<T>crates/vox-workflow-runtime/src/durable_promise.rs#L50-L53The single awaitable primitive. Use .await in Vox / .poll in Rust. Construction is private to the runtime — user code receives these as the result of a @remote call, an activity dispatch, a signal(), or a side_effect { … } block. The activity_id uniquely identifies the work item in the durable journal.
fndurable_promise::activity_idpub fn activity_id(&self) -> &strcrates/vox-workflow-runtime/src/durable_promise.rs#L91-L93The stable activity_id that identifies this unit of work in the journal.
fndurable_promise::from_serialisedpub fn from_serialised<T: DeserializeOwned>(crates/vox-workflow-runtime/src/durable_promise.rs#L134Deserialise a completed activity result from journal bytes (codegen path).
fndurable_promise::readypub fn ready<T: Serialize + Send + 'static>(activity_id: String, v: T) -> DurablePromise<T>crates/vox-workflow-runtime/src/durable_promise.rs#L146-L148Build a promise that resolves immediately with a known value (tests / codegen stubs).
enumduration_literal::DurationParseErrorpub enum DurationParseErrorcrates/vox-workflow-runtime/src/duration_literal.rs#L35-L44Error produced when a duration literal can’t be parsed. Implements std::error::Error so it composes with anyhow::Result and the codegen emit’s compile-time validation.
fnduration_literal::parse_duration_strpub fn parse_duration_str(s: &str) -> Result<Duration, DurationParseError>crates/vox-workflow-runtime/src/duration_literal.rs#L76-L131Parse a duration literal. See module docs for the accepted grammar. On error returns a structured [DurationParseError] — callers decide whether to convert to a compile-time diagnostic (vox_codegen::emit_main_boot) or a runtime anyhow::Error (workflow::plan::parse_duration_ms_str).
structfile_journal::FileJournalTrackerpub struct FileJournalTrackercrates/vox-workflow-runtime/src/file_journal.rs#L143-L151Append-only file-backed [WorkflowTracker] implementation. Flush cadence is profile-driven (spec §10): construct with [FileJournalTracker::with_profile] to adopt the platform’s [JournalFlushStrategy]. [FileJournalTracker::new] keeps the historical desktop behavior (every append is synced to the device before returning, plus a defensive periodic flush).
fnfile_journal::newpub fn new(path: impl Into<PathBuf>) -> Result<Self>crates/vox-workflow-runtime/src/file_journal.rs#L159-L161Open (or create) the file journal at path and replay any existing entries into the in-memory index. Equivalent to with_profile(path, RuntimeProfile::Desktop) — the historical behavior for every existing caller.
fnfile_journal::with_profilepub fn with_profile(path: impl Into<PathBuf>, profile: RuntimeProfile) -> Result<Self>crates/vox-workflow-runtime/src/file_journal.rs#L174-L176Open the journal with the flush behavior dictated by profile (profile.journal_flush_strategy()): - [RuntimeProfile::Desktop] → [JournalFlushStrategy::Periodic]: per-append device sync (the historical crash-safety contract, which strictly satisfies the periodic bound) plus a defensive background flusher at the strategy’s interval. - [RuntimeProfile::Mobile] → [JournalFlushStrategy::OnLifecycle]: appends are handed to the OS but the device sync is deferred to [Suspendable::suspend], which the host calls from the iOS/Android backgrounding hook. No background flusher thread (battery budget).
fnfile_journal::with_flush_strategypub fn with_flush_strategy(crates/vox-workflow-runtime/src/file_journal.rs#L180Open the journal with an explicit [JournalFlushStrategy] (the policy value [RuntimeProfile::journal_flush_strategy] produces).
fnfile_journal::pathpub fn path(&self) -> &Pathcrates/vox-workflow-runtime/src/file_journal.rs#L242-L244The path on disk where this journal is being written.
fnfile_journal::recorded_countpub fn recorded_count(&self) -> usizecrates/vox-workflow-runtime/src/file_journal.rs#L247-L249The number of recorded activity completions currently in memory.
fnfile_journal::flush_strategypub fn flush_strategy(&self) -> JournalFlushStrategycrates/vox-workflow-runtime/src/file_journal.rs#L252-L254The flush policy this tracker was constructed with.
fnfile_journal::has_periodic_flusherpub fn has_periodic_flusher(&self) -> boolcrates/vox-workflow-runtime/src/file_journal.rs#L258-L260Whether a background periodic flusher thread is running (desktop [JournalFlushStrategy::Periodic] profile only).
fnfile_journal::periodic_flush_countpub fn periodic_flush_count(&self) -> u64crates/vox-workflow-runtime/src/file_journal.rs#L264-L269How many times the periodic flusher has synced the journal. Always 0 for [JournalFlushStrategy::OnLifecycle] trackers.