Crate vsh 

Primary Rust SDK for VSH.

The implementation remains isolated in vsh-runtime; this crate is the stable application-facing registry handle.

Structs

AccessSet

Compact set of path capabilities denied by a protected rule.

ApprovalBinding

Exact fields covered by an independent approval grant.

ApprovalGrant

An independent approval bound to one exact transaction and expiry window.

ApprovalId

The digest identity of one exact bounded approval grant.

ArtifactLimits

Hard allocation and cardinality bounds for durable approval artifacts.

BaseSnapshot

An immutable metadata manifest with content that becomes immutable on first capture.

BlobId

The content digest of an immutable blob.

BlobStore

Filesystem-backed immutable content-addressed blob storage.

CallPolicy

Immutable pre-call policy used on the Monty hot path.

CanonicalDiff

Stable, path-ordered virtual filesystem diff.

CanonicalDiffMetrics

Work performed while deriving one canonical diff.

CapturedContent

Bytes captured between two metadata observations of the same host node.

CommitConfig

Hard bounds applied before durable commit work begins.

CommitPlan

Borrowed exact transaction artifact accepted by the trusted committer.

CommitReceipt

Compact proof that an exact transaction reached verified durable state.

CommitReservation

Non-cloneable proof that one transaction won the atomic commit reservation.

CommitResolution

Result of resolving a prepared commit request.

Committer

Capability-rooted workspace snapshot, revalidation, commit, and recovery engine.

ContentLoadError

Error returned by a lazy snapshot content loader.

DataDirectory

A pinned capability for VSH’s durable data directory.

DataDirectoryError

Failure to create or pin a durable VSH data directory.

DeniedAccess

A denied path capability, retained even when sandboxed code catches the exception.

DenyManifest

Deterministic denial payload.

DiffDigest

The digest identity of one canonical virtual filesystem diff.

DiffEntry

One path change in a canonical virtual filesystem diff.

DirectoryDigest

The digest identity of one observed directory listing.

EffectEvent

One sequence-numbered observed effect.

ExecutionLimits

Per-execution limits enforced independently from Monty’s bytecode tracker.

ExecutionOutcome

Successful result of a process-local Monty execution.

ExecutionStats

Host-side counters from one execution.

FileStamp

Metadata identity captured for one immutable base-snapshot node.

FileStoreConfig

Hard bounds for the dependency-free compacting transaction state store.

FileTransactionStore

Durable cross-process transaction state using only the Rust standard library.

HookConfig

Trusted, transaction-bound configuration for one commit hook.

HookDecisionRecord

Provenance for the hook decision applied to one exact event.

HookHandlerError

Contained handler failure. Runtime resolution applies fail-closed semantics first.

HookId

The opaque digest identity of one configured commit hook.

HookedRuntime

Native runtime plus a host-owned commit handler.

InProcessConfig

Configuration for the process-local Monty correctness harness.

InProcessMonty

Process-local typed adapter used for correctness tests and trusted embedding.

IntentDigest

The digest identity of transaction intent supplied out of band.

MemoryTransactionStore

Process-local reference backend for state-machine and concurrency correctness.

NoFaults

Production fault injector that never interrupts work.

NodeState

Canonical state of a virtual filesystem node.

PlatformFileId

Platform-specific identity of a host filesystem node.

PolicyDigest

The digest identity of one deterministic policy configuration.

PolicyInput

Inputs observed by deterministic transaction policy.

PolicyThresholds

Deterministic thresholds for escalation and hard denial.

PrincipalId

The opaque digest identity of an independent approval principal.

ProgramDigest

The digest identity of the exact untrusted program source.

ProtectedRule

One canonical protected-path rule.

ReadObservation

Dependency observed while virtual code was executing.

ReadSetDigest

The digest identity of one canonical transaction read set.

Receipt

Compact proof of virtual execution, policy, and optional verified commit.

RecoveryConflict

Fail-closed recovery result requiring operator resolution.

RecoveryReport

Aggregate result of scanning durable commit journals.

RequestEvent

Immutable, bounded evidence supplied to a commit hook.

RequestEventId

The digest identity of one exact commit-hook request event.

ReviewContent

Hash-verified bytes for one transaction-owned path/content identity.

RiskManifest

Bounded evidence shown to a fresh approval principal.

RiskMetrics

Exact bounded metrics used for a deterministic policy decision.

RunRequest

One borrowed native execution request.

Runtime

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

RuntimeConfig

Immutable runtime configuration shared by Rust and PyO3 callers.

RuntimeConfigDigest

The digest identity of security-relevant runtime configuration.

SnapshotBuilder

Builder for one immutable snapshot manifest.

SnapshotId

The digest identity of an immutable base snapshot.

SnapshotLimits

Bounds for eager host metadata traversal; file and link bytes remain lazy.

SnapshotMetrics

Observable snapshot size and lazy-materialization state.

StageTimings

Monotonic stage costs recorded without string allocation in the hot path.

SubprocessConfig

Configuration for the crash-isolated, typed Monty subprocess adapter.

SubprocessMonty

A short-lock worker pool backed by Monty’s official typed subprocess protocol.

TransactionBinding

Exact immutable inputs bound into an approval and commit identity.

TransactionId

The digest identity of an exact VSH transaction.

TransactionIdentityInput

Inputs used to construct an approval-bound transaction identity.

TransactionPolicy

Deterministic transaction policy and its pre-call capability rules.

TransactionRecord

The storage-facing identity and state of a transaction.

TransitionError

An invalid persisted transaction transition.

VPath

A normalized, workspace-relative virtual path.

VerificationFailure

Expected and observed state for a failed operation or final-state check.

VfsMetrics

Transaction-local virtual filesystem size counters.

VirtualFs

Copy-on-write filesystem over one immutable snapshot.

VirtualRoot

A validated absolute namespace prefix exposed to Monty.

WorkerFailure

Failure reported by the supervised subprocess boundary.

WritePrecondition

Base state that must still hold before a path may be written.

WriteSetDigest

The digest identity of one canonical transaction write set.

Enums

AccessKind

Semantic capability requested for one virtual path.

ApprovalGrantError

Invalid approval grant input.

ArtifactError

Durable pending-artifact encoding or validation failure.

BlobStoreError

A blob-store operation failed or immutable content did not verify.

CommitError

Trusted-commit, revalidation, or recovery failure.

CommitPlanError

Invalid or unbounded immutable commit artifact.

CommitPreparation

Prepared commit evidence, revalidated by the runtime before resolution.

ContentVersion

Content identity carried by a node state.

DenyReason

Stable reason a deterministic policy must reject a transaction.

DiffKind

Semantic category of one canonical diff entry.

Effect

Semantic event emitted by the operation that actually observed or changed state.

EffectOrigin

Source of an observed virtual filesystem effect.

ExecutionError

Failure of a Monty execution adapter.

ExecutionLimitExceeded

Why execution stopped before a normal Monty result was produced.

FaultPoint

Deterministic crash boundary exposed to fault-injection tests.

HookBaseline

Deterministic policy outcome that caused a hook event.

HookDecision

Decision returned by a hook handler.

HookScope

Which policy-authorized commit candidates a hook may inspect.

HookVerdict

Stable normalized outcome retained next to a hook resolution.

HostError

Capability-scoped host filesystem observation failure.

JournalError

Durable operation-journal or commit-marker validation failure.

MontyFailurePhase

Phase in which Monty raised an exception outside sandboxed exception handling.

MontyObject

An owned Python value exchanged between Monty and its host.

MontyType

The Python type of a value at the host boundary — the public mirror of the internal runtime Type enum.

NodeKind

The semantic kind of a virtual filesystem node.

OsFunctionCall

Tagged dispatch value for OS-level operations.

ParseDigestError

A canonical 32-byte lowercase/uppercase hexadecimal identifier was malformed.

PatternError

Invalid protected-path pattern.

PlanDecodeError

Durable commit-plan decoding failure.

PolicyConfigError

Invalid deterministic-policy threshold configuration.

PolicyDecision

Final deterministic transaction decision.

PolicyProfile

Built-in deterministic transaction posture.

ReceiptDetail

Amount of canonical change detail retained in a receipt.

ResultCompatibility

Host surface whose value-conversion contract must accept an execution result.

ResultCompatibilityError

A bounded Monty result cannot be represented by the selected host surface.

RevalidationConflict

One exact dependency mismatch detected before the first host mutation.

RiskFlag

Why an otherwise valid transaction requires an independent approval principal.

RunMode

Whether one call stops after policy or commits deterministic auto-approvals.

RuntimeDecision

Deterministic policy result retained in the native receipt.

SnapshotError

Snapshot content-capture and manifest validation failure.

TransactionState

A persisted transaction state.

TransactionStoreError

Atomic transaction-store failure.

VPathError

A reason a virtual path was rejected.

VfsError

Virtual filesystem operation failure.

VirtualPathError

A Monty path that cannot name a node in the configured virtual root.

VirtualRootError

Invalid synthetic-root configuration.

VshError

Stable native error surface shared with the Python exception mapper.

WorkerFailureKind

Supervised-worker failure category.

Constants

DEFAULT_SECRET_PATTERNS

Secret-like paths denied by the default call policy for every access kind.

DEFAULT_VIRTUAL_ROOT

Canonical absolute path exposed to sandboxed code for the workspace root.

VERSION

The VSH semantic version shared by native and Python packages.

Traits

CommitHook

Synchronous Rust hook. Async hosts should drive prepare_commit and resolve_commit around their own executor instead of blocking the runtime.

ContentLoader

Capability-scoped provider for one lazily captured snapshot node.

FaultInjector

Test seam for simulating process loss at durable boundaries.

TransactionStore

Atomic transaction-state operations required by the runtime and committer.

Functions

bind_transaction

Bind every approval-relevant artifact into one immutable transaction identity.

engine_kind

Identify the implementation behind all public SDK surfaces.

read_set_digest

Canonically hash a read dependency set.

validate_result_compatibility

Validate one result before any host mutation that a binding could report as failed.

write_set_digest

Canonically hash write preconditions.

Type Aliases

ExecutionBudget

Request-scoped resource caps enforced by the Monty/VFS adapter.