luft_core/
lib.rs

1//! # luft-core
2//!
3//! **Frozen contracts, scheduler, journal, and state management.**
4//!
5//! `luft-core` is the zero-dependency foundation of the Luft ecosystem.
6//! It defines the traits, types, scheduling logic, and persistence interfaces
7//! that every other crate builds on. Types defined here are **frozen contracts**
8//! — breaking changes are treated as major version bumps.
9//!
10//! ## Module Overview
11//!
12//! | Module | Responsibility |
13//! |--------|---------------|
14//! | [`contract`] | Cross-crate traits and types: [`AgentBackend`], [`AgentTask`], [`AgentResult`], [`AgentEvent`], [`Finding`] |
15//! | [`scheduler`] | Concurrency-limited agent dispatcher with retry and journal callbacks |
16//! | [`journal`] | Checkpoint store for run resume — write agent results, read on restart |
17//! | [`state`] | Run/phase state machine: [`RunCheckpoint`], [`CheckpointStatus`] |
18//! | [`run_dir`] | Filesystem layout helpers for `.luft/runs/<run-id>/` |
19//!
20//! ## Stability Guarantees
21//!
22//! - **Traits** ([`AgentBackend`], [`JournalCallback`]): signatures are stable
23//!   within a minor version. Implementations in downstream crates are safe.
24//! - **Structs** ([`AgentTask`], [`AgentResult`], [`RunCheckpoint`]): fields
25//!   are `pub` and additive only (new fields require `#[serde(default)]` or a
26//!   major bump).
27//! - **Enums** ([`AgentStatus`], [`BackendError`], [`RunStatus`]): variants are
28//!   additive — new variants may appear in minor releases.
29//!
30//! ## Feature Flags
31//!
32//! | Feature | Description |
33//! |---------|-------------|
34//! | `testing` | Exports [`MockBackend`], [`MockFileBackend`], and test data generators |
35//!
36//! [`AgentBackend`]: contract::backend::AgentBackend
37//! [`AgentTask`]: contract::backend::AgentTask
38//! [`AgentResult`]: contract::backend::AgentResult
39//! [`AgentEvent`]: contract::event::AgentEvent
40//! [`Finding`]: contract::finding::Finding
41//! [`JournalCallback`]: scheduler::JournalCallback
42//! [`MockBackend`]: mock_backend::MockBackend
43//! [`MockFileBackend`]: mock_file_backend::MockFileBackend
44
45pub mod contract;
46pub mod journal;
47pub mod run_dir;
48pub mod scheduler;
49pub mod state;
50
51#[cfg(any(feature = "testing", test))]
52pub mod mock_backend;
53#[cfg(feature = "testing")]
54pub mod mock_file_backend;
55#[cfg(feature = "testing")]
56pub mod mock_gen;
57
58pub use contract::*;
59pub use journal::{
60    gc_runs, AgentCacheKey, CompositeJournalCallback, JournalError, JournalStore, ResumeContext,
61    RunCreationMode,
62};
63pub use scheduler::{
64    BackendRegistry, JournalCallback, RetryPolicy, Scheduler, SchedulerConfig, SchedulerError,
65};
66pub use state::{
67    get_run_store, list_runs, AgentResultCache, CheckpointStatus, PhaseSummary, RunCheckpoint,
68    RunStore,
69};
70
71#[cfg(feature = "testing")]
72pub use mock_backend::{FailKind, MockBackend, MockBehavior};
73#[cfg(feature = "testing")]
74pub use mock_file_backend::{MockFileBackend, MockStats, MockStatsSnapshot};
luft_core/lib.rs

luft_core/
lib.rs
