Struct Runtime 

pub struct Runtime { /* private fields */ }

One native VSH engine instance with no process-global execution lock.

Implementations

impl Runtime

pub fn open(config: RuntimeConfig) -> Result<Self, VshError>

Open one capability-rooted runtime and recover durable interrupted commits.

Errors

Returns an error when blob storage, workspace capability setup, recovery, or fail-closed recovery conflict handling fails.

Examples found in repository

examples/native_benchmark.rs (lines 355-357)

fn open_runtime(root: &Path, worker: &Path) -> Result<Runtime, Box<dyn Error>> {
    Ok(Runtime::open(
        RuntimeConfig::new(root).with_worker_path(worker),
    )?)
}

examples/staged_release.rs (line 36)

fn main() -> Result<(), Box<dyn Error>> {
    let workspace = Workspace::new()?;
    fs::create_dir(workspace.0.join("templates"))?;
    fs::write(
        workspace.0.join("templates/service.toml"),
        b"channel = \"dev\"\n",
    )?;
    let runtime = Runtime::open(RuntimeConfig::new(&workspace.0))?;
    let code = include_str!("staged_release.monty");
    let preview = runtime.preview(RunRequest::new(code).with_detail(ReceiptDetail::Full))?;
    assert!(matches!(
        preview.decision,
        RuntimeDecision::PendingApproval(_)
    ));
    assert_eq!(preview.changed_paths, 3);
    assert!(!workspace.0.join("release").exists());
    assert_eq!(
        preview
            .changes
            .iter()
            .map(|entry| entry.path.as_str())
            .collect::<Vec<_>>(),
        ["release", "release/README.txt", "release/app.toml"]
    );
    let now = u64::try_from(SystemTime::now().duration_since(UNIX_EPOCH)?.as_millis())?;
    // A rename is a semantic risk even if it only rearranges generated files.
    // Production code must authenticate a reviewer before this trusted call.
    runtime.approve(
        preview.transaction,
        PrincipalId::digest_label("fixture-reviewer"),
        now,
        now + 30_000,
    )?;
    let committed = runtime.commit(preview.transaction, now)?;
    assert_eq!(committed.transaction, preview.transaction);
    assert!(committed.commit.is_some());
    assert_eq!(
        fs::read_to_string(workspace.0.join("release/app.toml"))?,
        "channel = \"stable\"\n"
    );
    assert_eq!(
        fs::read_to_string(workspace.0.join("release/README.txt"))?,
        "channel=stable\n"
    );
    assert!(!workspace.0.join("release/service.toml").exists());
    println!(
        "Committed {} reviewed paths: {}",
        committed.changed_paths, committed.transaction
    );
    Ok(())
}

pub const fn startup_recovery(&self) -> &RecoveryReport

Return the startup recovery work completed before accepting requests.

pub fn run(&self, request: RunRequest<'_>) -> Result<Receipt, VshError>

Execute, evaluate, and optionally auto-commit one exact transaction.

Errors

Returns a typed error for snapshot, execution, diff, state, binding, reservation, revalidation, commit, or recovery failures. Deterministic policy denial is a successful receipt and never reaches the committer.

pub fn preview(&self, request: RunRequest<'_>) -> Result<Receipt, VshError>

Force preview-only behavior regardless of the request’s mode field.

Errors

Returns the same typed failures as Self::run.

Examples found in repository

examples/native_benchmark.rs (line 198)

fn sample(runtime: &Runtime, code: &str, intent: &str) -> Result<Sample, Box<dyn Error>> {
    let started = Instant::now();
    let receipt = runtime.preview(RunRequest::new(code).with_intent(intent))?;
    let wall_ns = elapsed_ns(started);
    if receipt.state == TransactionState::AutoApproved
        && !runtime.discard_preview(receipt.transaction)?
    {
        return Err(io::Error::other("runtime did not retain its auto-approved preview").into());
    }
    Ok(Sample {
        wall_ns,
        internal_ns: receipt.timings.total_ns,
        stages: receipt.timings.into(),
        state: receipt.state,
        changed_paths: u64::try_from(receipt.changed_paths).unwrap_or(u64::MAX),
    })
}

examples/staged_release.rs (line 38)

fn main() -> Result<(), Box<dyn Error>> {
    let workspace = Workspace::new()?;
    fs::create_dir(workspace.0.join("templates"))?;
    fs::write(
        workspace.0.join("templates/service.toml"),
        b"channel = \"dev\"\n",
    )?;
    let runtime = Runtime::open(RuntimeConfig::new(&workspace.0))?;
    let code = include_str!("staged_release.monty");
    let preview = runtime.preview(RunRequest::new(code).with_detail(ReceiptDetail::Full))?;
    assert!(matches!(
        preview.decision,
        RuntimeDecision::PendingApproval(_)
    ));
    assert_eq!(preview.changed_paths, 3);
    assert!(!workspace.0.join("release").exists());
    assert_eq!(
        preview
            .changes
            .iter()
            .map(|entry| entry.path.as_str())
            .collect::<Vec<_>>(),
        ["release", "release/README.txt", "release/app.toml"]
    );
    let now = u64::try_from(SystemTime::now().duration_since(UNIX_EPOCH)?.as_millis())?;
    // A rename is a semantic risk even if it only rearranges generated files.
    // Production code must authenticate a reviewer before this trusted call.
    runtime.approve(
        preview.transaction,
        PrincipalId::digest_label("fixture-reviewer"),
        now,
        now + 30_000,
    )?;
    let committed = runtime.commit(preview.transaction, now)?;
    assert_eq!(committed.transaction, preview.transaction);
    assert!(committed.commit.is_some());
    assert_eq!(
        fs::read_to_string(workspace.0.join("release/app.toml"))?,
        "channel = \"stable\"\n"
    );
    assert_eq!(
        fs::read_to_string(workspace.0.join("release/README.txt"))?,
        "channel=stable\n"
    );
    assert!(!workspace.0.join("release/service.toml").exists());
    println!(
        "Committed {} reviewed paths: {}",
        committed.changed_paths, committed.transaction
    );
    Ok(())
}

pub fn discard_preview( &self, transaction: TransactionId, ) -> Result<bool, VshError>

Forget one process-local auto-approved preview without mutating the host.

Durable approval-required artifacts are never removed by this method. false means this runtime did not retain the supplied preview.

Errors

Returns an error only when the bounded pending-artifact lock was poisoned.

Examples found in repository

examples/native_benchmark.rs (line 201)

fn sample(runtime: &Runtime, code: &str, intent: &str) -> Result<Sample, Box<dyn Error>> {
    let started = Instant::now();
    let receipt = runtime.preview(RunRequest::new(code).with_intent(intent))?;
    let wall_ns = elapsed_ns(started);
    if receipt.state == TransactionState::AutoApproved
        && !runtime.discard_preview(receipt.transaction)?
    {
        return Err(io::Error::other("runtime did not retain its auto-approved preview").into());
    }
    Ok(Sample {
        wall_ns,
        internal_ns: receipt.timings.total_ns,
        stages: receipt.timings.into(),
        state: receipt.state,
        changed_paths: u64::try_from(receipt.changed_paths).unwrap_or(u64::MAX),
    })
}

pub fn approve( &self, transaction: TransactionId, principal: PrincipalId, issued_at_unix_ms: u64, expires_at_unix_ms: u64, ) -> Result<TransactionRecord, VshError>

Bind an independent, expiring approval to one exact pending transaction.

Errors

Returns an error for an invalid time window, missing transaction, mismatched binding, wrong state, or internal artifact-state mismatch.

Examples found in repository

examples/staged_release.rs (lines 56-61)

fn main() -> Result<(), Box<dyn Error>> {
    let workspace = Workspace::new()?;
    fs::create_dir(workspace.0.join("templates"))?;
    fs::write(
        workspace.0.join("templates/service.toml"),
        b"channel = \"dev\"\n",
    )?;
    let runtime = Runtime::open(RuntimeConfig::new(&workspace.0))?;
    let code = include_str!("staged_release.monty");
    let preview = runtime.preview(RunRequest::new(code).with_detail(ReceiptDetail::Full))?;
    assert!(matches!(
        preview.decision,
        RuntimeDecision::PendingApproval(_)
    ));
    assert_eq!(preview.changed_paths, 3);
    assert!(!workspace.0.join("release").exists());
    assert_eq!(
        preview
            .changes
            .iter()
            .map(|entry| entry.path.as_str())
            .collect::<Vec<_>>(),
        ["release", "release/README.txt", "release/app.toml"]
    );
    let now = u64::try_from(SystemTime::now().duration_since(UNIX_EPOCH)?.as_millis())?;
    // A rename is a semantic risk even if it only rearranges generated files.
    // Production code must authenticate a reviewer before this trusted call.
    runtime.approve(
        preview.transaction,
        PrincipalId::digest_label("fixture-reviewer"),
        now,
        now + 30_000,
    )?;
    let committed = runtime.commit(preview.transaction, now)?;
    assert_eq!(committed.transaction, preview.transaction);
    assert!(committed.commit.is_some());
    assert_eq!(
        fs::read_to_string(workspace.0.join("release/app.toml"))?,
        "channel = \"stable\"\n"
    );
    assert_eq!(
        fs::read_to_string(workspace.0.join("release/README.txt"))?,
        "channel=stable\n"
    );
    assert!(!workspace.0.join("release/service.toml").exists());
    println!(
        "Committed {} reviewed paths: {}",
        committed.changed_paths, committed.transaction
    );
    Ok(())
}

pub fn commit( &self, transaction: TransactionId, now_unix_ms: u64, ) -> Result<Receipt, VshError>

Consume the single-use reservation and commit one previewed transaction.

Errors

Returns an error for missing artifacts, expired approval, replay, stale host dependencies, commit/recovery failures, or internal binding mismatch.

Examples found in repository

examples/staged_release.rs (line 62)

fn main() -> Result<(), Box<dyn Error>> {
    let workspace = Workspace::new()?;
    fs::create_dir(workspace.0.join("templates"))?;
    fs::write(
        workspace.0.join("templates/service.toml"),
        b"channel = \"dev\"\n",
    )?;
    let runtime = Runtime::open(RuntimeConfig::new(&workspace.0))?;
    let code = include_str!("staged_release.monty");
    let preview = runtime.preview(RunRequest::new(code).with_detail(ReceiptDetail::Full))?;
    assert!(matches!(
        preview.decision,
        RuntimeDecision::PendingApproval(_)
    ));
    assert_eq!(preview.changed_paths, 3);
    assert!(!workspace.0.join("release").exists());
    assert_eq!(
        preview
            .changes
            .iter()
            .map(|entry| entry.path.as_str())
            .collect::<Vec<_>>(),
        ["release", "release/README.txt", "release/app.toml"]
    );
    let now = u64::try_from(SystemTime::now().duration_since(UNIX_EPOCH)?.as_millis())?;
    // A rename is a semantic risk even if it only rearranges generated files.
    // Production code must authenticate a reviewer before this trusted call.
    runtime.approve(
        preview.transaction,
        PrincipalId::digest_label("fixture-reviewer"),
        now,
        now + 30_000,
    )?;
    let committed = runtime.commit(preview.transaction, now)?;
    assert_eq!(committed.transaction, preview.transaction);
    assert!(committed.commit.is_some());
    assert_eq!(
        fs::read_to_string(workspace.0.join("release/app.toml"))?,
        "channel = \"stable\"\n"
    );
    assert_eq!(
        fs::read_to_string(workspace.0.join("release/README.txt"))?,
        "channel=stable\n"
    );
    assert!(!workspace.0.join("release/service.toml").exists());
    println!(
        "Committed {} reviewed paths: {}",
        committed.changed_paths, committed.transaction
    );
    Ok(())
}

pub fn prepare_commit( &self, transaction: TransactionId, ) -> Result<CommitPreparation, VshError>

Freeze one exact commit candidate before invoking an external handler.

No handler code runs in this method. Process-local auto-approved previews are made durable before an event is returned, so a crash can regenerate the same event from the exact transaction artifact.

Errors

Returns a typed store, artifact, configuration, or evidence error.

pub fn resolve_commit( &self, preparation: &CommitPreparation, decision: &HookDecision, now_unix_ms: u64, ) -> Result<CommitResolution, VshError>

Apply one hook decision to the exact prepared transaction.

The preparation is revalidated against durable state and regenerated evidence, so callers cannot substitute a transaction or event after the handler returns.

Errors

Returns a typed event-binding, state, approval, store, or commit error. The exact preparation is checked again before any decision changes host files.

pub fn fail_hook(&self, preparation: &CommitPreparation) -> Result<(), VshError>

Apply fail-closed state after a handler exception, timeout, or cancellation.

Errors

Returns a typed store or artifact error if automatic approval cannot be moved into the existing pending-approval state.

pub fn recover(&self) -> Result<RecoveryReport, VshError>

Recover all durable commit artifacts under this runtime’s capability root.

Errors

Returns a typed commit/recovery error for corrupt or unsafe journals.

pub fn transaction( &self, transaction: TransactionId, ) -> Result<TransactionRecord, VshError>

Return one persisted lifecycle record.

Errors

Returns VshError::Store when the transaction does not exist.