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, Skill
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::list_run_dirs;

pub use state::AgentResultCache;

pub use state::AgentSessionCheckpoint;

pub use state::CheckpointBackend;

pub use state::CheckpointStatus;

pub use state::PhaseSummary;

pub use state::RunCheckpoint;

pub use testing::CallRecord;

pub use testing::CountingBackend;

pub use testing::CrashBackend;

pub use testing::SharedBackend;

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.

in_memory_backend

In-memory CheckpointBackend for tests and lightweight usage.

journal

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

json_to_lua

Encode serde_json::Value as a Lua expression.

mock_backend

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

params

Shared parameter parsing for workflow tool consumers.

query

Query DTO types shared between the CLI and storage layers.

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.

session

Process-local mapping between Luft session ids and backend protocol ids.

state

Progress persistence and resume for long-running workflows.

testing

Test utilities for resume and integration testing.