Module ApplicationState 

ApplicationState Module

Responsibilities

This module defines the central, shared, thread-safe state for the entire Mountain application. It serves as the single source of truth for all runtime state including:

State Management:

• Main ApplicationState struct with all runtime state
• Thread-safe access via Arc<Mutex<...>> wrappers
• State transitions and invariants enforcement
• Recovery mechanisms for corrupted state
• Disk persistence for memento (workspace and global) state

Data Structures:

• Data Transfer Objects (DTOs) for various components
• Type-safe state representations
• Serialization/deserialization support
• Validation for state updates

Internal Utilities:

• File I/O and path resolution
• State initialization and loading
• Extension scanning and population
• URL serialization helpers
• Recovery utilities for corrupted state

Architectural Role

The ApplicationState module is the state management layer of Mountain:

UI ──► Commands ──► ApplicationState (State) ──► Providers/Services
                     │
                     ↓
                  Disk (Persistence)

Design Principles:

1. Single Source of Truth: All state lives in one place
2. Thread Safety: All state is protected by Arc<Mutex<…>>
3. Recovery-Oriented: Comprehensive error handling and recovery
4. Type Safety: Strong typing at all levels
5. Observability: Comprehensive logging for state changes

VS Code Reference:

This module borrows from VS Code’s state management patterns in:

• vs/base/parts/storage/common/storageService.ts - Storage management
• vs/workbench/services/environment/common/environmentService.ts - Environment state
• vs/platform/workspace/common/workspace.ts - Workspace state
• vs/workbench/services/extensions/common/extensions.ts - Extension state

Key concepts:

• Global vs workspace-scoped storage
• Memento (state serialization) for crash recovery
• Thread-safe state access with proper locking
• State validation and invariants

Key Components

ApplicationState

The central state struct containing all runtime state:

Workspace State:

• WorkspaceFolders - Currently open workspace folders
• WorkspaceConfigurationPath - Path to workspace config
• IsTrusted - Workspace trust status
• WindowState - Window size, position, etc.
• ActiveDocumentURI - Currently active document

Configuration & Storage:

• Configuration - Merged configuration state
• GlobalMemento - Global storage (keys → values)
• WorkspaceMemento - Workspace-scoped storage
• Memento paths for persistence

Extension & Provider Management:

• CommandRegistry - Registered commands
• LanguageProviders - Language feature providers
• ScannedExtensions - Discovered extensions
• ExtensionScanPaths - Paths to search for extensions
• EnabledProposedAPIs - Proposed API permissions

Feature-specific State:

• DiagnosticsMap - Compiler/diagnostic errors
• OpenDocuments - Currently open documents
• OutputChannels - Output channel state
• ActiveTerminals - Active terminal instances
• ActiveWebviews - Active webview panels
• ActiveCustomDocuments - Custom editor state
• ActiveStatusBarItems - Status bar entries
• ActiveTreeViews - Tree view providers
• SourceControlManagement* - SCM provider state

IPC & UI State:

• PendingUserInterfaceRequests - Pending UI interactions (dialogs, etc.)

DTOs

Type-safe representations of state components:

• WorkspaceFolderStateDTO - Workspace folder representation
• DocumentStateDTO - Document metadata and content
• ExtensionDescriptionStateDTO - Extension metadata
• TreeViewStateDTO - Tree view state
• WebviewStateDTO - Webview panel state
• etc.

Internal

Helper functions for state management:

• LoadInitialMementoFromDisk - Load persistent state from disk
• ResolveMementoStorageFilePath - Resolve storage paths
• ScanAndPopulateExtensions - Scan for extensions
• AnalyzeTextLinesAndEOL - Text content analysis
• Recovery utilities and error handling

Thread Safety

All state is protected by Arc<Mutex<...>> for thread-safe access:

pub struct ApplicationState {
	pub WorkspaceFolders:Arc<Mutex<Vec<WorkspaceFolderStateDTO>>>,
	pub Configuration:Arc<Mutex<MergedConfigurationStateDTO>>,
	// ... all fields follow this pattern
}

Best Practices:

• Always lock mutexes before accessing state
• Use map_err(MapLockError) for lock error handling
• Release locks as soon as possible (use RAII)
• Avoid nested locks to prevent deadlocks

State Persistence

Memento System

Mountain uses a memento system for state persistence:

Global Memento:

• Lives at {AppData}/globalStorage.json
• Contains global application state
• Persists across workspace changes

Workspace Memento:

• Lives at {AppData}/workspaceStorage/{workspace-id}/storage.json
• Contains workspace-specific state
• Changes when workspace changes

Recovery:

• Corrupted JSON files are backed up with timestamps
• Empty maps are returned on parse errors
• Directories are created automatically

Error Handling

All state operations return Result<T, CommonError> where:

• Ok(T) - Successful operation with result
• Err(CommonError) - Error with context

Error types:

• StateLockPoisoned - Mutex was poisoned (another thread panicked)
• FileSystemIO - File system operations failed
• SerializationError - JSON parsing failed
• Unknown - Uncategorized errors

Recovery mechanisms:

• MapLockErrorWithRecovery - Attempt recovery from poisoned locks
• SafeStateOperation - Safe state operation with recovery
• RecoverApplicationState - Comprehensive state recovery

State Transitions

Valid state transitions:

Uninitialized → Default State → Workspace Loaded → Workspace Unloaded
     ↓                ↓                 ↓                  ↓
   Load           Recover          Update Memento      Clean Up

Invariants:

• Workspace identifier is computed from folder or config
• Memento paths are synced with workspace changes
• Provider handles are monotonically increasing
• Unique IDs are never reused

TODOs

High Priority:

• Add state migration support for version changes
• Implement state diffing for better debugging
• Add state snapshots for rollback support

Medium Priority:

• Add state compression for large workspaces
• Implement incremental memento updates
• Add state validation on load

Low Priority:

• Add state analytics and metrics
• Implement state cloning for testing
• Add state export/import functionality

Re-exports

pub use State::ApplicationState::ApplicationState;

pub use State::ApplicationState::MapLockError;

pub use State::ApplicationState::MapLockErrorWithRecovery;

pub use State::ApplicationState::StateOperationResult;

pub use State::ConfigurationState;

pub use State::ExtensionState;

pub use State::FeatureState;

pub use State::UIState;

pub use State::WorkspaceState;

pub use Internal::ExtensionScanner;

pub use Internal::PathResolution;

pub use Internal::Persistence;

pub use Internal::Recovery;

pub use Internal::Serialization;

pub use Internal::TextProcessing;

Modules

DTO

Data Transfer Objects for serialization.

Internal

Internal utility sub-modules for persistence, scanning, etc.

State

State management sub-modules.