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`], [`Skill`] |
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//! [`Skill`]: contract::skill::Skill
42//! [`JournalCallback`]: scheduler::JournalCallback
43//! [`MockBackend`]: mock_backend::MockBackend
44//! [`MockFileBackend`]: mock_file_backend::MockFileBackend
45
46pub mod contract;
47pub mod in_memory_backend;
48pub mod journal;
49pub mod run_dir;
50pub mod scheduler;
51pub mod session;
52pub mod state;
53
54pub mod json_to_lua;
55pub mod mock_backend;
56#[cfg(feature = "testing")]
57pub mod mock_file_backend;
58#[cfg(feature = "testing")]
59pub mod mock_gen;
60pub mod params;
61pub mod query;
62pub mod testing;
63
64pub use contract::*;
65pub use journal::{
66    gc_runs, AgentCacheKey, CompositeJournalCallback, JournalError, JournalStore, ResumeContext,
67    RunCreationMode,
68};
69pub use scheduler::{
70    BackendRegistry, JournalCallback, RetryPolicy, Scheduler, SchedulerConfig, SchedulerError,
71};
72pub use state::{
73    list_run_dirs, AgentResultCache, AgentSessionCheckpoint, CheckpointBackend, CheckpointStatus,
74    PhaseSummary, RunCheckpoint,
75};
76
77#[cfg(feature = "testing")]
78pub use mock_backend::{FailKind, MockBackend, MockBehavior};
79#[cfg(feature = "testing")]
80pub use mock_file_backend::{MockFileBackend, MockStats, MockStatsSnapshot};
81pub use testing::{CallRecord, CountingBackend, CrashBackend, SharedBackend};
luft_core/lib.rs

luft_core/
lib.rs
