ryo-storage 0.1.0

//! Global RYO storage for session persistence and replay.
//!
//! This module provides persistent storage for session transaction logs,
//! enabling **Git-like reproducibility**: given an initial state and a sequence
//! of mutations, the same result can be deterministically reproduced.
//!
//! # Architecture Overview
//!
//! The storage system is designed with a **3-layer architecture** inspired by
//! [Command Sourcing] and [Event Sourcing] patterns from game simulation systems:
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────────────────┐
//! │  Layer 1: Mutation (Functional Layer)                                   │
//! │  ─────────────────────────────────────────────────────────────────────  │
//! │  - trait Mutation { apply(), describe(), ... }                          │
//! │  - Maximum extensibility: 100+ mutation types supported                 │
//! │  - No serialization responsibility                                      │
//! │  - See: ryo_mutations                                                 │
//! └─────────────────────────────────────────────────────────────────────────┘
//!                             ↓ generates at execution time
//! ┌─────────────────────────────────────────────────────────────────────────┐
//! │  Layer 2: MutationRecord (Recording Layer)                              │
//! │  ─────────────────────────────────────────────────────────────────────  │
//! │  - Serializable record of each mutation                                 │
//! │  - Contains: MutationSpec + StateRef(pre) + StateRef(post)              │
//! │  - Enables determinism verification during replay                       │
//! │  - See: crate::txlog::TxAction::MutationApplied                         │
//! └─────────────────────────────────────────────────────────────────────────┘
//!                             ↓ references
//! ┌─────────────────────────────────────────────────────────────────────────┐
//! │  Layer 3: StateStore (State Layer)                                      │
//! │  ─────────────────────────────────────────────────────────────────────  │
//! │  - Content-addressed storage for file states                            │
//! │  - Like GPU textures: managed separately but composable                 │
//! │  - Immutable: StateRef = hash of content                                │
//! │  - See: StateRef, StateStore                                            │
//! └─────────────────────────────────────────────────────────────────────────┘
//! ```
//!
//! # Design Principles
//!
//! ## Command Sourcing with Verification
//!
//! Unlike pure Command Sourcing (which requires determinism) or pure Event
//! Sourcing (which stores results), we use a **hybrid approach**:
//!
//! ```text
//! MutationRecord = MutationSpec + pre_state + post_state
//!                  (Command)      (验证用)    (验证用)
//! ```
//!
//! - **MutationSpec**: The "what" - serializable mutation intent
//! - **pre_state**: Expected state before mutation (for verification)
//! - **post_state**: Expected state after mutation (for verification)
//!
//! This allows:
//! 1. **Normal replay**: Apply mutations sequentially
//! 2. **Verified replay**: Check pre/post states match expectations
//! 3. **Partial replay**: Start from any checkpoint with known state
//!
//! ## Comparison with Git
//!
//! | Concept     | Git                    | RYO                           |
//! |-------------|------------------------|-------------------------------|
//! | State       | Blob (content-hashed)  | StateRef (content-hashed)     |
//! | Operation   | Diff (computed)        | MutationSpec (recorded)       |
//! | History     | Commit chain           | TxLog (MutationRecord chain)  |
//! | Checkpoint  | Tag/Branch             | Named Snapshot                |
//!
//! Key difference: Git stores **states**, RYO stores **operations**.
//! But both can reconstruct history through their chain.
//!
//! # Replay Flow
//!
//! ```text
//! 1. Load initial state from StateStore (or checkpoint)
//! 2. For each MutationRecord in TxLog:
//!    a. (Optional) Verify current state == record.pre_state
//!    b. Reconstruct Mutation from MutationSpec
//!    c. Apply mutation: state' = mutation.apply(state)
//!    d. (Optional) Verify state' == record.post_state
//! 3. Final state is the replay result
//! ```
//!
//! # Directory Structure
//!
//! ```text
//! ~/.ryo/
//! ├── sessions/              # Session transaction logs
//! │   ├── {uuid}.txlog.json
//! │   └── ...
//! ├── states/                # (Future) Content-addressed state storage
//! │   ├── ab/cd1234...       # Sharded by hash prefix
//! │   └── ...
//! ├── index.json             # Session metadata index
//! └── config.toml            # (Future) Global configuration
//! ```
//!
//! # Usage
//!
//! ```ignore
//! use ryo_core::storage::{RyoStorage, StateRef, StateStore};
//! use ryo_core::txlog::TxLog;
//!
//! // Create global storage
//! let mut storage = RyoStorage::global()?;
//! storage.ensure_init()?;
//!
//! // Dump a session
//! let log: TxLog = /* ... */;
//! let session_id = storage.dump(&log)?;
//!
//! // Load and replay
//! let loaded = storage.load(&session_id)?;
//! loaded.replay(&state_store)?;
//!
//! // Query sessions
//! let all = storage.list_sessions()?;
//! let project_sessions = storage.sessions_for_project(Path::new("/my/project"))?;
//! ```
//!
//! # References
//!
//! - [Command Pattern - Game Programming Patterns](https://gameprogrammingpatterns.com/command.html)
//! - [Event Sourcing - Martin Fowler](https://martinfowler.com/eaaDev/EventSourcing.html)
//! - [Command Sourcing vs Event Sourcing](https://thinkbeforecoding.com/post/2013/07/28/Event-Sourcing-vs-Command-Sourcing)
//!
//! [Command Sourcing]: https://thinkbeforecoding.com/post/2013/07/28/Event-Sourcing-vs-Command-Sourcing
//! [Event Sourcing]: https://martinfowler.com/eaaDev/EventSourcing.html

mod autosave;
mod config;
mod format;
mod index;
mod mode;
mod project;
mod state;
mod store;

pub use autosave::AutoSaveLogger;
pub use config::{CliConfig, ConfigError, GlobalConfig, ServerConfig};
pub use format::{get_serializer, Format, FormatError, FormatResult, JsonFormat, SessionFormat};
pub use index::{SessionIndex, SessionMeta};
pub use mode::TxLogMode;
pub use project::{is_process_alive, ProjectIndex, ProjectMeta, ProjectServerOptions};
pub use state::{FileStateSnapshot, InMemoryStateStore, StateRef, StateStore, WorkspaceSnapshot};
pub use store::{RyoStorage, StorageError, StorageResult};