crackle_runtime/lib.rs
1#![deny(unsafe_code)]
2//! # crackle-runtime
3//!
4//! *The crackle glaze forms in the cooling, not the firing.*
5//!
6//! A task execution framework where tasks have a **firing phase** (hot execution)
7//! and a **cooling phase** (deferred pattern detection). During cooling, the runtime
8//! detects emergent patterns across completed tasks that weren't visible during execution.
9//!
10//! ## Core Metaphor
11//!
12//! In pottery, the most beautiful moment is not the firing — it's the cooling. The glaze
13//! and clay contract at different rates, producing craze lines: unique, unrepeatable
14//! patterns that record the history of the transformation. You cannot design these cracks.
15//! You can only create the conditions for them and get out of the way.
16//!
17//! Similarly, `crackle-runtime` executes tasks (firing) and then observes what patterns
18//! emerge across completed tasks during a cooling phase — patterns that were invisible
19//! during the heat of execution.
20//!
21//! ## Quick Start
22//!
23//! ```
24//! use crackle_runtime::{CrackleTask, Kiln, ThermalProfile, GlazeLayer, TaskOutput};
25//! use std::time::Duration;
26//!
27//! /// A simple task that produces a number
28//! struct NumberTask { value: f64 }
29//!
30//! impl CrackleTask for NumberTask {
31//! type Output = f64;
32//!
33//! fn fire(&self) -> TaskOutput<Self::Output> {
34//! TaskOutput::new(self.value, vec![("magnitude".into(), self.value.abs())])
35//! }
36//! }
37//!
38//! // Build a kiln with fast cooling (more cracks, more patterns)
39//! let mut kiln = Kiln::new(ThermalProfile::fast_cooling());
40//!
41//! // Fire tasks
42//! kiln.fire_task(NumberTask { value: 3.14 }).unwrap();
43//! kiln.fire_task(NumberTask { value: 2.71 }).unwrap();
44//!
45//! // Let the kiln cool and detect patterns
46//! let patterns = kiln.cool();
47//!
48//! // Inspect what emerged
49//! for pattern in &patterns {
50//! println!("{:?}: {}", pattern.kind(), pattern.description());
51//! }
52//! ```
53
54mod error;
55mod glaze;
56mod information;
57mod kiln;
58mod patterns;
59mod profile;
60mod task;
61
62pub use error::{CrackleError, Result};
63pub use glaze::GlazeLayer;
64pub use kiln::{Kiln, TaskEntry};
65pub use patterns::{
66 ClusteringPattern, ConservationPattern, CorrelationPattern, CracklePattern, PatternKind,
67 PhaseTransitionPattern,
68};
69pub use profile::{CoolingRate, ThermalProfile};
70pub use task::{CrackleTask, TaskMetadata, TaskOutput, Timestamp};
71pub use information::{
72 entropy, joint_entropy, jsd, kl_divergence, mutual_information, permutation_entropy,
73 transfer_entropy,
74};
75
76#[cfg(test)]
77mod tests;