Crate luft_core 

luft-core

Frozen contracts, scheduler, journal, and state management.

luft-core is the zero-dependency foundation of the Luft ecosystem. It defines the traits, types, scheduling logic, and persistence interfaces that every other crate builds on. Types defined here are frozen contracts — breaking changes are treated as major version bumps.

Module Overview

Module	Responsibility
contract	Cross-crate traits and types: AgentBackend, AgentTask, AgentResult, AgentEvent, Finding
scheduler	Concurrency-limited agent dispatcher with retry and journal callbacks
journal	Checkpoint store for run resume — write agent results, read on restart
state	Run/phase state machine: RunCheckpoint, CheckpointStatus
run_dir	Filesystem layout helpers for .luft/runs/<run-id>/

Stability Guarantees

• Traits (AgentBackend, JournalCallback): signatures are stable within a minor version. Implementations in downstream crates are safe.
• Structs (AgentTask, AgentResult, RunCheckpoint): fields are pub and additive only (new fields require #[serde(default)] or a major bump).
• Enums (AgentStatus, BackendError, RunStatus): variants are additive — new variants may appear in minor releases.

Feature Flags

Feature	Description
testing	Exports MockBackend, MockFileBackend, and test data generators

Re-exports

pub use journal::gc_runs;

pub use journal::AgentCacheKey;

pub use journal::CompositeJournalCallback;

pub use journal::JournalError;

pub use journal::JournalStore;

pub use journal::ResumeContext;

pub use journal::RunCreationMode;

pub use scheduler::BackendRegistry;

pub use scheduler::JournalCallback;

pub use scheduler::RetryPolicy;

pub use scheduler::Scheduler;

pub use scheduler::SchedulerConfig;

pub use scheduler::SchedulerError;

pub use state::get_run_store;

pub use state::list_runs;

pub use state::AgentResultCache;

pub use state::CheckpointStatus;

pub use state::PhaseSummary;

pub use state::RunCheckpoint;

pub use state::RunStore;

pub use testing::CallRecord;

pub use testing::CountingBackend;

pub use testing::CrashBackend;

pub use testing::SharedBackend;

pub use testing::completed_span_names;

pub use testing::read_checkpoint;

pub use testing::wait_for_calls;

pub use contract::*;

Modules

contract

Frozen contracts (code-design §1). These types are the shared basis for all modules; once reviewed they should change rarely. A companion CONTRACTS.md may track the freeze.

journal

Journal / Resume — checkpoint persistence with replay semantics (M1).

mock_backend

MockBackend (§2.8) — a deterministic test backend. Compiled under test or the testing feature so integration tests can reuse it.

run_dir

Human-readable run directory naming: {slug}_{unix_timestamp}.

scheduler

Concurrent scheduler (M1, §2): concurrency limiting, per-run quota, retry, cancellation, and event reporting.

state

Progress persistence and resume for long-running workflows.

testing

Test utilities for resume and integration testing.