Grove - Deep Dive

Grove provides the technical foundation Rust/WASM extension host within the Land project. Grove provides a native, sandboxed environment for running VS Code extensions compiled to WebAssembly or native Rust, complementing the Node.js-based Cocoon host.

Architecture

Grove is organized into five layers: the extension host controller that manages the lifecycle, the WASM runtime that provides sandboxed execution, the VS Code API bridge that presents the standard extension API, the transport layer that communicates with Mountain, and shared utility modules.

graph TB
    subgraph "Grove - Rust/WASM Extension Host"
        Main["main.rs / lib.rs<br/>Binary + Library entry"]
        Binary["Binary/<br/>CLI and startup"]
        Host["Host/<br/>Extension Host Controller"]
        ExtHost["Host/ExtensionHost.rs<br/>Main controller"]
        ExtMgr["Host/ExtensionManager.rs<br/>Discovery and loading"]
        Activation["Host/Activation.rs<br/>Activation events"]
        Lifecycle["Host/Lifecycle.rs<br/>Extension lifecycle"]
        APIBridge["Host/APIBridge.rs<br/>VS Code API facade"]
        WASM["WASM/<br/>WebAssembly Runtime"]
        Runtime["WASM/Runtime.rs<br/>WASMtime engine + store"]
        ModuleLoader["WASM/ModuleLoader.rs<br/>Module compilation"]
        MemoryMgr["WASM/MemoryManager.rs<br/>Memory allocation"]
        HostBridge["WASM/HostBridge.rs<br/>Host-WASM function bridge"]
        Transport["Transport/<br/>Communication Strategies"]
        GRPCTransport["Transport/gRPCTransport.rs<br/>gRPC via Mountain"]
        IPCTransport["Transport/IPCTransport.rs<br/>Local IPC"]
        WASMTransport["Transport/WASMTransport.rs<br/>Direct WASM calls"]
        Protocol["Protocol/<br/>Spine connection"]
    end

    subgraph "Mountain - Rust Backend"
        VineGRPC["Vine gRPC Server"]
    end

    Main --> Binary
    Binary --> Host
    Host --> ExtHost
    ExtHost --> ExtMgr
    ExtHost --> Activation
    ExtHost --> Lifecycle
    ExtHost --> APIBridge
    APIBridge --> WASM
    WASM --> Runtime
    WASM --> ModuleLoader
    WASM --> MemoryMgr
    WASM --> HostBridge
    ExtHost --> Transport
    Transport --> GRPCTransport
    Transport --> IPCTransport
    Transport --> WASMTransport
    ExtHost --> Protocol
    GRPCTransport --> VineGRPC

Key Modules

Path	Description
`Source/lib.rs`	Library root; exports public API for integration and testing
`Source/main.rs`	Binary entry point; parses CLI and starts the extension host
`Source/Binary/`	CLI argument handling and standalone vs connected mode selection
`Source/Host/ExtensionHost.rs`	Main controller: coordinates extension loading, activation, and service provision
`Source/Host/ExtensionManager.rs`	Extension discovery, manifest parsing, and loading
`Source/Host/Activation.rs`	Activation event processing (`onLanguage`, `onCommand`, etc.)
`Source/Host/Lifecycle.rs`	Extension activate/deactivate lifecycle management
`Source/Host/APIBridge.rs`	VS Code API facade implementation for Rust/WASM extensions
`Source/WASM/Runtime.rs`	WASMtime engine and store management with memory limits
`Source/WASM/ModuleLoader.rs`	WASM module compilation, caching, and instantiation
`Source/WASM/MemoryManager.rs`	WASM linear memory allocation and bounds enforcement
`Source/WASM/HostBridge.rs`	Host function exports to WASM modules
`Source/WASM/FunctionExport.rs`	Registered host functions available to extension WASM code
`Source/Transport/Strategy.rs`	Transport strategy trait for pluggable communication
`Source/Transport/gRPCTransport.rs`	gRPC communication with Mountain via `tonic`
`Source/Transport/IPCTransport.rs`	Unix/Windows IPC transport for same-host communication
`Source/Transport/WASMTransport.rs`	Direct in-process WASM function call transport
`Source/Protocol/SpineConnection.rs`	Spine protocol client for extension host coordination

Data Flow

sequenceDiagram
    participant Mountain as Mountain Core
    participant Grove as Grove Extension Host
    participant WASM as WASM Runtime
    participant Extension as WASM Extension

    Mountain->>Grove: GroveService.ActivateExtension (gRPC via Vine)
    Grove->>Grove: ExtensionManager.load(manifest)
    Grove->>WASM: ModuleLoader.compile(wasm_bytes)
    WASM->>Grove: Compiled module
    Grove->>WASM: Runtime.instantiate(module, host_functions)
    WASM->>Extension: WASM module initialized
    Extension->>WASM: Call host function (e.g. vscode.workspace.readFile)
    WASM->>Grove: HostBridge dispatch
    Grove->>Mountain: Forward service call via Transport
    Mountain->>Grove: Service result
    Grove->>WASM: Return value to extension
    WASM->>Extension: Result available

Integration Points

Connecting Element	Direction	Mechanism	Description
Mountain	Bidirectional	gRPC via Vine	Mountain activates extensions; Grove forwards API calls back to Mountain
Cocoon	Sibling	Shared API surface	Grove implements the same VS Code API surface as Cocoon for extension portability

Configuration

Option	CLI Flag / Feature	Default	Description
Standalone mode	`--standalone`	off	Run without Mountain connection for testing
Extension path	`--extension`	unset	Load a specific extension directly
Transport	feature flag	gRPC	Select `grpc`, `ipc`, or `wasm` transport via Cargo features
Memory limit	runtime config	platform default	Per-extension WASM memory ceiling enforced by WASMtime
WASM build target	`wasm32-wasi`	native	Extensions must target `wasm32-wasi` for WASM mode

Cargo features

Feature	Description
`grpc`	gRPC transport support (included in `default`)
`wasm`	WASMtime WASM runtime (included in `default`)
`ipc`	Unix/Windows IPC transport (Unix only)
`all`	All features enabled