aimx/aim/
mod.rs

1//! Agentic Inference Markup (AIM) file format support
2//!
3//! This module provides support for the Agentic Inference Markup (AIM) file format used by Imogen.
4//! AIM is a text-based file format that stores workflows as hierarchical directories and files,
5//! with each `.aim` file representing a workflow containing a list of rules.
6//!
7//! # File Format Structure
8//!
9//! AIM files use a journal-based approach for version control:
10//!
11//! ```text
12//! workspace.aim     # Root workspace file
13//! workspace.jnl     # Journal file for version tracking
14//! workspace/
15//! ├── parent.aim    # Workflow file
16//! ├── parent.jnl    # Journal for parent workflow
17//! ├── parent/       # Subdirectory for child workflows
18//! │   ├── child.aim # Child workflow
19//! │   └── child.jnl # Journal for child workflow
20//! └── sibling.aim   # Sibling workflow
21//! ```
22//!
23//! # Version Control System
24//!
25//! AIM uses a two-component versioning system:
26//! - **Epoch**: Major version number that increments for structural changes
27//! - **Partial**: Minor version number for incremental updates within the same epoch
28//!
29//! Versions are tracked in journal files (`.jnl`) that map version numbers to byte offsets
30//! in the corresponding AIM files, enabling efficient random access to specific versions.
31//!
32//! # Concurrency Model
33//!
34//! AIM implements a Multi-Version Concurrency Control (MVCC) model:
35//! - **Readers**: Unlimited concurrent access to consistent snapshots without blocking
36//! - **Writers**: Fine-grained per-workflow locking for exclusive write access
37//! - **Lazy Loading**: Workflows loaded on-demand with reference-counted sharing
38//!
39//! # Modules
40//!
41//! - [`config`] - Application configuration management
42//! - [`journal`] - Version journaling and persistence
43//! - [`lock_manager`] - Fine-grained workflow locking for concurrent access
44//! - [`read`] - Journaled workflow reading utilities
45//! - [`version`] - Version header parsing and management
46//!
47//! # Re-exports
48//!
49//! The following items are re-exported for convenient access:
50//!
51//! - [`AppName`] - Application name configuration
52//! - [`get_config`], [`get_config_mut`] - Global configuration access
53//! - [`Journal`] - Journal entry representation
54//! - [`LockManager`], [`get_lock_manager`] - Workflow lock management
55//! - [`read_latest`], [`read_version`] - Workflow reading functions
56//! - [`Version`], [`parse_version`] - Version parsing and management
57
58pub mod config;
59pub mod journal;
60pub mod lock_manager;
61pub mod read;
62pub mod version;
63
64pub use config::{AppName, Config, get_config, get_config_mut};
65pub use journal::{Journal, to_journal_path, journal_file, journal_load, journal_save};
66pub use lock_manager::{LockManager, get_lock_manager};
67pub use read::{read_latest, read_version};
68pub use version::{Version, parse_version};
aimx/aim/mod.rs

aimx/aim/
mod.rs
