Crate deep_causality_haft

Expand description

The deep_causality_haft crate provides foundational traits and utilities for implementing Higher-Kinded Types (HKTs) and functional programming patterns (Functor, Applicative, Monad, Foldable) in Rust.

This crate is a core component of the deep_causality project, enabling the construction of flexible and robust type-encoded effect systems.

§Core Concepts

Higher-Kinded Types (HKTs): Abstractions over type constructors (e.g., Option<T>, Vec<T>). This allows writing generic code that works across different container types.
Functor: Defines the fmap operation for mapping a function over a type constructor.
Applicative: Extends Functor with pure (to lift values) and apply (to apply functions within a context).
Monad: Provides the bind operation for sequencing computations that produce effectful values.
Foldable: Defines the fold operation for reducing a data structure to a single value.
Type-Encoded Effect Systems: A mechanism to explicitly track and manage side-effects (like errors, logging, counters) using Rust’s type system, ensuring compile-time verification.

§Modules

core: Core HKT definitions and machinery.
algebra: Algebraic traits (Functor, Monad, etc.).
effect_system: Type-encoded effect system traits.
extensions: Concrete HKT witness implementations for standard Rust types.
utils_tests: Internal utilities and test-specific effect types.

§Usage

This crate is primarily intended for internal use within the deep_causality project to build its core abstractions. However, the traits and concepts can be generally applied to other Rust projects requiring advanced functional programming patterns and effect management.

Re-exports§

pub use crate::iso::NaturalIso;
pub use crate::iso::NaturalIso2;
pub use crate::iso::NaturalIso3;
pub use crate::iso::NaturalIso4;
pub use crate::iso::NaturalIso5;

Modules§

iso: Tier 3 isomorphism traits — natural isomorphisms between HKT witnesses.
utils_tests: This module provides utility types and implementations primarily used for testing and demonstrating the type-encoded effect system within deep_causality_haft.

Structs§

ArrowBuilder: A fluent builder over the Arrow algebra that hides the combinator types.
ArrowTerm: The typed façade over ArrowCore: a free-arrow term whose In/Out objects are tracked in the type so that only sound wiring composes.
BTreeMapWitness: BTreeMapWitness<K> is a zero-sized type that acts as a Higher-Kinded Type (HKT) witness for the BTreeMap<K, V> type constructor, where the key type K is fixed.
BoxWitness: BoxWitness is a zero-sized type that acts as a Higher-Kinded Type (HKT) witness for the Box<T> type constructor. It allows Box to be used with generic functional programming traits like Functor, Applicative, Foldable, and Monad.
Choice: The coproduct sum +++: route each summand to its own arrow — Either<A, C> → Either<B, D> from F: A → B and G: C → D.
Cofree: The cofree comonad on a functor F: head :< f (Cofree f a).
CofreeWitness: The HKT witness for the cofree comonad over the functor F (dual of FreeWitness).
Compose: Sequential composition f >>> g: the arrow that runs f, then g on its output.
Fanin: Fanin |||: the coproduct elimination — both branches converge on one output type, Either<A, C> → B from F: A → B and G: C → B. This is the universal map of the coproduct (haft.either.coproduct_universal) as an arrow.
Fanout: Fanout &&&: feeds one input to two arrows — A → (B, C) from f: A → B and g: A → C. Requires the input to be Clone (it is duplicated to both arrows).
First: Strength on the first component: lifts F: A → B to (A, C) → (B, C), passing the second component through unchanged.
FnMorphism: The canonical function-pointer carrier for Morphism: an arrow A → B is a plain fn(A) -> B.
FreeWitness: The HKT witness for the free monad over the operation functor F.
Fun: The category of functions Fun: Hom<B> = B, identity is |a| a, composition is g ∘ f.
HashMapWitness: HashMapWitness<K> is a zero-sized type that acts as a Higher-Kinded Type (HKT) witness for the HashMap<K, V> type constructor, where the key type K is fixed.
Id: The identity arrow A → A — the unit of composition.
IoAndThen: The monadic bind of the IO monad: run the inner action, feed its output to f, then run the action f returns. Short-circuits on the first error (the second action does not run).
IoFail: The zero of the IO monad: an action that fails with error and performs no side effect.
IoMap: The functor map of the IO monad: run the inner action, then apply f to its successful output.
IoMapErr: Transforms the error channel of an IO action, leaving the success path untouched.
IoPure: The unit of the IO monad: an action that yields value with no side effect.
Kleisli: The Kleisli category of a monad M (Mac Lane §VI.5; Moggi, Notions of Computation and Monads, 1991): Hom<B> = M::Type<B>, identity is pure, and composition is bind (compose(f, g)(a) = bind(f(a), g), the Kleisli arrow >=>).
Left: left: lift F: A → B to Either<A, C> → Either<B, C>, acting on the left summand and passing a Right value through unchanged.
Lift: Lifts a plain function F: Fn(A) -> B into an Arrow A → B.
LinkedListWitness: LinkedListWitness is a zero-sized type that acts as a Higher-Kinded Type (HKT) witness for the LinkedList<T> type constructor. It allows LinkedList to be used with generic functional programming traits like Functor, Applicative, Foldable, and Monad.
NoConstraint: The universal constraint — every type satisfies it.
OptionToVec: The natural transformation Option ⇒ Vec: None ↦ [], Some a ↦ [a].
OptionWitness: OptionWitness is a zero-sized type that acts as a Higher-Kinded Type (HKT) witness for the Option<T> type constructor. It allows Option to be used with generic functional programming traits like Functor, Applicative, Foldable, and Monad.
Placeholder: A zero-sized type used purely as a marker or placeholder when implementing Higher-Kinded Type (HKT) traits for concrete types.
ResultUnboundWitness: ResultUnboundWitness is a zero-sized type that acts as a witness for the Result<A, B> type constructor where both parameters are unbound.
ResultWitness: ResultWitness<E> is a zero-sized type that acts as a Higher-Kinded Type (HKT) witness for the Result<T, E> type constructor, where the error type E is fixed.
Right: right: lift F: A → B to Either<C, A> → Either<C, B>, acting on the right summand and passing a Left value through unchanged.
Second: Strength on the second component: lifts F: A → B to (C, A) → (C, B), passing the first component through unchanged.
Split: The monoidal product ***: runs two arrows in parallel on a pair — (A, C) → (B, D) from f: A → B and g: C → D.
SymMonoidal: The generators of the cartesian symmetric-monoidal PROP: copy/discard (the copy comonoid), merge/unit (the merge monoid), and swap (the symmetry). A zero-sized namespace — the generators are ad-hoc polymorphic (over any value, or any Monoid), so they are associated functions rather than trait methods.
Tuple2Witness: Tuple2Witness acts as a witness for the (A, B) type constructor.
Tuple3Witness: Tuple3Witness acts as a witness for the (A, B, C) type constructor.
VecDequeWitness: VecDequeWitness is a zero-sized type that acts as a Higher-Kinded Type (HKT) witness for the VecDeque<T> type constructor. It allows VecDeque to be used with generic functional programming traits like Functor and Foldable.
VecWitness: VecWitness is a zero-sized type that acts as a Higher-Kinded Type (HKT) witness for the Vec<T> type constructor. It allows Vec to be used with generic functional programming traits like Functor, Applicative, Foldable, and Monad.

Enums§

ArrowCore: The erased core: the free arrow over a generator set G, stored as first-order data.
ArrowVal: The value universe interpreted terms flow through: a binary tree with payload leaves.
Either: A value of one of two types, Left(L) or Right(R).
Free: The free monad on a functor F: Pure a | Suspend (f (Free f a)).

Traits§

Adjunction: The Adjunction trait defines a pair of adjoint functors L (Left) and R (Right) with an optional runtime Context.
AliasAdjunction: Alias trait for Adjunction providing more intuitive method names.
AliasCoMonad: Alias trait for CoMonad providing more intuitive method names.
AliasFoldable: Alias trait for Foldable providing more intuitive method names.
AliasFunctor: Alias trait for Functor providing more intuitive method names.
AliasMonad: Alias trait for Monad providing more intuitive method names.
AliasProfunctor: Alias trait for Profunctor providing more intuitive method names.
Applicative: The Applicative trait extends Functor and Pure by providing the apply operation to apply a function wrapped in a context to a value wrapped in a context.
Arrow: A value-level arrow In → Out: a runnable, composable transformation.
Bifunctor: The Bifunctor trait allows mapping over both arguments of a type constructor F<A, B>.
Category: A category: an identity morphism on every object and associative composition of compatible morphisms (Mac Lane, Categories for the Working Mathematician, §I.1).
CloneFunctor: Witness capability: an HKT functor whose Type<T> can be cloned whenever the payload T: Clone.
CoMonad: The CoMonad trait represents a comonadic context, which is the dual of a Monad.
CyberneticLoop: The CyberneticLoop trait models a complete feedback control system involving 5 distinct components.
DebugFunctor: Witness capability: an HKT functor whose Type<T> can be Debug-formatted whenever the payload T: Debug.
Effect3: Effect3: The Bridge Trait for Arity 3 Type Constructors.
Effect4: Effect4: The Bridge Trait for Arity 4 Type Constructors.
Effect5: Effect5: The Bridge Trait for Arity 5 Type Constructors.
Effect3Unbound: Effect3Unbound: Parametric Effect Trait for Arity 3.
Effect4Unbound: Effect4Unbound: Parametric Effect Trait for Arity 4.
Effect5Unbound: Effect5Unbound: Parametric Effect Trait for Arity 5.
EndoArrow: The value-level realization of the Endomorphism monoid, as a type extension: iteration of an endo-arrow (an Arrow whose input and output type coincide).
Endomorphism: The type-preserving fragment of Morphism: arrows T → T.
EqFunctor: Witness capability: an HKT functor whose Type<T> can be compared structurally whenever the payload T: PartialEq.
Foldable: The Foldable trait abstracts over data structures that can be reduced to a single summary value.
Functor: The Functor trait abstracts over types that can be mapped over.
HKT: Trait for a Higher-Kinded Type (HKT) with one type parameter (arity 1).
HKT2: Trait for a Higher-Kinded Type (HKT) with two type parameters (arity 2).
HKT3: Trait for a Higher-Kinded Type (HKT) with three type parameters (arity 3).
HKT4: Trait for a Higher-Kinded Type (HKT) with four type parameters (arity 4).
HKT5: Trait for a Higher-Kinded Type (HKT) with five type parameters (arity 5).
HKT2Unbound: Trait for a Higher-Kinded Type (HKT) with two unbound generic parameters (Arity 2).
HKT3Unbound: Trait for a Higher-Kinded Type (HKT) with three generic parameters (Arity 3).
HKT4Unbound: Trait for a Higher-Kinded Type (HKT) with four generic parameters (Arity 4).
HKT5Unbound: Trait for a Higher-Kinded Type (HKT) with five generic parameters (Arity 5).
HKT6Unbound: Trait for a Higher-Kinded Type (HKT) with six generic parameters (Arity 6).
IoAction: A deferred description of an input/output computation.
LogAddEntry
LogAppend: Trait for types that can append log entries from another instance of themselves.
LogEffect
LogSize
Monad: The Monad trait extends Functor and Pure by providing the bind operation for sequencing computations that produce effectful values.
MonadEffect3: Monadic logic for an Arity 3 type after it has been partially applied via Effect3.
MonadEffect4: Monadic logic for an Arity 4 type after it has been partially applied via Effect4.
MonadEffect5: Monadic logic for an Arity 5 type after it has been partially applied via Effect5.
MonadEffect3Unbound: Monadic logic for Parametric Effects (Arity 3 Unbound).
MonadEffect4Unbound: Monadic logic for Parametric Effects (Arity 4 Unbound).
MonadEffect5Unbound: Monadic logic for Parametric Effects (Arity 5 Unbound).
MonoidalMerge: The MonoidalMerge trait models the “fusion” or “interaction” of two contexts to produce a third.
Morphism: The explicit typed-arrow base: a family of arrows P::Type<A, B> (think A → B) with an identity arrow and the ability to apply an arrow to an input.
NaturalTransformation: A natural transformation F ⇒ G between two HKT functors.
ParametricMonad: The ParametricMonad (or Indexed Monad) trait allows for monadic computations where the type of the underlying state can change at each step.
Profunctor: The Profunctor trait represents a type constructor that is contravariant in its first argument and covariant in its second argument.
Pure: The Pure trait provides the ability to lift a value into a context.
RiemannMap: The RiemannMap trait models high-arity geometric interactions, specifically the Riemann Curvature Tensor and Scattering Matrices.
Satisfies: Marker trait indicating that type T satisfies constraint C.
Traversable: The Traversable trait abstracts over data structures that can be “traversed” or “sequenced” in a way that preserves effects. It combines the capabilities of Functor (mapping over elements) and Foldable (reducing to a single value).

Functions§

arrow: Starts an arrow chain by lifting a function F: Fn(A) -> B into a builder.
io_fail: Build a failing IO action: the action that yields error and performs no IO.
io_pure: Lift a value into the IO monad: the action that yields value and performs no IO.