Added initial implementation of deep_causality_haft

Signed-off-by: Marvin Hansen <[email protected]>

Author: marvin-hansen

AGENTS.md

@@ -108,6 +108,8 @@ The reason is, Bazel cannot access util files from within the test folder, but i
 can access the full src folder during testing. As a result, test utils have to be fully
 tested to count towards the code coverage score.
 
+The usage of a prelude file is prohibited. 
+
 ## Code export
 
 * All public errors, traits, and errors are exported from src/lib.rs

Cargo.lock

@@ -8,6 +8,7 @@ members = [
     "deep_causality_algorithms",
     "deep_causality_data_structures",
     "deep_causality_discovery",
+    "deep_causality_haft",
     "deep_causality_macros",
     "deep_causality_num",
     "deep_causality_rand",

Cargo.toml

@@ -0,0 +1,37 @@
+load("@rules_rust//rust:defs.bzl", "rust_doc", "rust_doc_test", "rust_library", "rust_test")
+
+rust_library(
+    name = "deep_causality_haft",
+    srcs = glob([
+        "src/**",
+    ]),
+    crate_root = "src/lib.rs",
+    tags = [
+        "utils",
+        "HKT",
+        "HAFT",
+    ],
+    visibility = ["//visibility:public"],
+    deps = [
+
+    ],)
+
+rust_doc(
+    name = "doc",
+    crate = ":deep_causality_haft",
+    tags = ["doc"],
+    visibility = ["//visibility:public"],
+)
+
+rust_doc_test(
+    name = "doc_test",
+    crate = ":deep_causality_haft",
+    tags = ["doc-test"],
+    visibility = ["//visibility:public"],
+)
+
+rust_test(
+    name = "tests",
+    crate = ":deep_causality_haft",
+    srcs = glob(["tests/**"]),
+)

deep_causality_haft/BUILD.bazel

@@ -0,0 +1,19 @@
+[package]
+name = "deep_causality_haft"
+version = "0.1.0"
+edition = { workspace = true }
+rust-version = { workspace = true }
+license = { workspace = true }
+
+repository = "https://github.com/deepcausality/deep_causality.rs"
+authors = ["Marvin Hansen <[email protected]>", ]
+description = "HKT traits for for the deep_causality crate."
+documentation = "https://docs.rs/deep_causality"
+categories = ["development-tools"]
+keywords = ["HKT", "traits"]
+# Exclude all bazel files as these conflict with Bazel workspace when vendored.
+exclude = ["*.bazel", "*/*.bazel",  "*.bazel.*", "BUILD", "BUILD.bazel", "MODULE.bazel", ".bazelignore",".bazelrc", "tests/**/*"]
+
+
+[dependencies]
+

deep_causality_haft/Cargo.toml

@@ -0,0 +1,23 @@
+SPDX-License-Identifier: MIT
+
+Copyright (c) 2023 - The DeepCausality Authors. All Rights Reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deep_causality_haft/LICENSE

@@ -0,0 +1,96 @@
+# Deep Causality HAFT
+
+**HAFT: Higher-Order Abstract Functional Traits**
+
+`deep_causality_haft` is a sub-crate of the `deep_causality` project, providing traits for Higher-Kinded Types (HKTs) in Rust. This enables writing generic, abstract code that can operate over different container types like `Option<T>` and `Result<T, E>`.
+
+## What are Higher-Kinded Types?
+
+In Rust, types like `Option<T>` and `Vec<T>` are generic over a type `T`. We can think of `Option` and `Vec` as "type constructors": they take a type and produce a new type.
+
+A Higher-Kinded Type is an abstraction over these type constructors. It allows us to write functions that are generic not just over a type, but over the *shape* or *kind* of a type constructor. For example, we can write a function that works with any type constructor that can be mapped over (a `Functor`), without caring if it's an `Option`, a `Result`, or something else.
+
+This crate provides the fundamental traits (`HKT`, `HKT2`, `HKT3`) and functional traits (`Functor`, `Monad`) to enable this pattern.
+
+## Usage
+
+This crate uses a "witness" pattern to represent HKTs. For each type constructor (like `Option`), we define a zero-sized "witness" type (like `OptionWitness`) that implements the `HKT` trait.
+
+### Example: Using `Functor` with `Option`
+
+Here's how you can use the `Functor` trait with `Option` via its witness type, `OptionWitness`.
+
+```rust
+use deep_causality_haft::{Functor, HKT, OptionWitness};
+
+// Manual implementation of Functor for OptionWitness
+impl Functor<OptionWitness> for OptionWitness {
+    fn fmap<A, B, Func>(m_a: <OptionWitness as HKT>::Type<A>, f: Func) -> <OptionWitness as HKT>::Type<B>
+    where
+        Func: FnOnce(A) -> B,
+    {
+        m_a.map(f)
+    }
+}
+
+fn main() {
+    let opt_a = Some(5);
+    let f = |x| x * 2;
+
+    // Use the fmap function from our Functor implementation
+    let opt_b = OptionWitness::fmap(opt_a, f);
+    assert_eq!(opt_b, Some(10));
+
+    let opt_none: Option<i32> = None;
+    let opt_none_mapped = OptionWitness::fmap(opt_none, f);
+    assert_eq!(opt_none_mapped, None);
+}
+```
+
+### Example: Using `Functor` with `Result`
+
+Here's how you can use the `Functor` trait with `Result<T, E>` via its witness type, `ResultWitness<E>`. `HKT2` is used here because `Result` has two generic parameters, and we are fixing the error type `E`.
+
+```rust
+use deep_causality_haft::{Functor, HKT2, ResultWitness};
+
+// Manual implementation of Functor for ResultWitness
+impl<E> Functor<ResultWitness<E>> for ResultWitness<E>
+where
+    E: 'static,
+{
+    fn fmap<A, B, Func>(m_a: <ResultWitness<E> as HKT2<E>>::Type<A>, f: Func) -> <ResultWitness<E> as HKT2<E>>::Type<B>
+    where
+        Func: FnOnce(A) -> B,
+    {
+        m_a.map(f)
+    }
+}
+
+fn main() {
+    let res_a: Result<i32, String> = Ok(5);
+    let f = |x| x * 2;
+
+    // Use the fmap function from our Functor implementation
+    let res_b = ResultWitness::fmap(res_a, f);
+    assert_eq!(res_b, Ok(10));
+
+    let res_err: Result<i32, String> = Err("Error".to_string());
+    let res_err_mapped = ResultWitness::fmap(res_err, f);
+    assert_eq!(res_err_mapped, Err("Error".to_string()));
+}
+
+## Type-Encoded Effect System
+
+The `Effect3` and `MonadEffect3` traits provide a powerful mechanism for building a **type-encoded effect system**. This allows you to manage side-effects (like errors and logging) in a structured, safe, and composable way, which is particularly useful for building complex data processing pipelines.
+
+### How it Works
+
+1.  **Effects as Types**: Side-effects are represented by generic type parameters on a container (e.g., `E` for Error, `W` for Warning on a custom `MyEffect<T, E, W>` type).
+2.  **Rules as Traits**: The logic for how to handle and combine these effects is defined by implementing the `MonadEffect3` trait. For example, the `bind` function can specify that the pipeline should halt on an error while accumulating warnings.
+3.  **Compiler-Enforced Safety**: Because the effects are part of the type signature, the Rust compiler can statically verify that all effects are handled correctly. This prevents bugs and ensures that your pipeline code remains pure and focused on its core logic.
+4.  **Extensibility**: This pattern is extensible. If you need to manage more side-effects, you can introduce `HKT4` and `Effect4` traits to handle them, without having to rewrite your core pipeline logic.
+
+In essence, this crate provides the tools to build a small, powerful, and compile-time-checked effects library tailored perfectly for your application's needs, forming the foundation for building powerful, abstract, and reusable causal models in the `deep_causality` ecosystem.
+```
+

deep_causality_haft/README.md

@@ -0,0 +1,53 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+
+use deep_causality_haft::{Functor, Monad, OptionWitness, ResultWitness};
+
+fn main() {
+    println!("--- Option Example ---");
+
+    let opt_a = Some(5);
+    let f_map = |x| x * 2;
+    let opt_b = OptionWitness::fmap(opt_a, f_map);
+    println!("fmap(Some(5), |x| x * 2) = {:?}", opt_b);
+    assert_eq!(opt_b, Some(10));
+
+    let f_bind = |x| Some(x + 1);
+    let opt_c = OptionWitness::bind(opt_b, f_bind);
+    println!("bind(Some(10), |x| Some(x + 1)) = {:?}", opt_c);
+    assert_eq!(opt_c, Some(11));
+
+    let pure_val_opt = OptionWitness::pure(100);
+    println!("pure(100) = {:?}", pure_val_opt);
+    assert_eq!(pure_val_opt, Some(100));
+
+    println!("\n--- Result Example ---");
+
+    type MyResult<T> = Result<T, String>;
+
+    let res_a: MyResult<i32> = Ok(10);
+    let f_map_res = |x: i32| x.to_string();
+    let res_b = ResultWitness::fmap(res_a, f_map_res);
+    println!("fmap(Ok(10), |x| x.to_string()) = {:?}", res_b);
+    assert_eq!(res_b, Ok("10".to_string()));
+
+    let f_bind_res = |s: String| Ok(s.len());
+    let res_c = ResultWitness::bind(res_b, f_bind_res);
+    println!("bind(Ok(\"10\"), |s| Ok(s.len())) = {:?}", res_c);
+    assert_eq!(res_c, Ok(2));
+
+    let res_err: MyResult<i32> = Err("An error occurred".to_string());
+    let res_err_mapped = ResultWitness::fmap(res_err.clone(), f_map_res);
+    println!("fmap(Err(...), |x| x.to_string()) = {:?}", res_err_mapped);
+    assert_eq!(res_err_mapped, Err("An error occurred".to_string()));
+
+    let res_err_bound = ResultWitness::bind(res_err, |x| Ok(x + 1));
+    println!("bind(Err(...), |x| Ok(x + 1)) = {:?}", res_err_bound);
+    assert_eq!(res_err_bound, Err("An error occurred".to_string()));
+
+    let pure_val_res: MyResult<i32> = ResultWitness::pure(200);
+    println!("pure(200) = {:?}", pure_val_res);
+    assert_eq!(pure_val_res, Ok(200));
+}

deep_causality_haft/examples/simple_haft.rs

@@ -0,0 +1,74 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+
+use crate::fp::{Functor, Monad};
+use crate::kind::{HKT, OptionWitness};
+use crate::kind::{HKT2, ResultWitness};
+
+// Manual implementation of Functor for OptionWitness
+impl Functor<OptionWitness> for OptionWitness {
+    fn fmap<A, B, Func>(
+        m_a: <OptionWitness as HKT>::Type<A>,
+        f: Func,
+    ) -> <OptionWitness as HKT>::Type<B>
+    where
+        Func: FnOnce(A) -> B,
+    {
+        m_a.map(f)
+    }
+}
+
+// Manual implementation of Monad for OptionWitness
+impl Monad<OptionWitness> for OptionWitness {
+    fn pure<T>(value: T) -> <OptionWitness as HKT>::Type<T> {
+        Some(value)
+    }
+
+    fn bind<A, B, Func>(
+        m_a: <OptionWitness as HKT>::Type<A>,
+        f: Func,
+    ) -> <OptionWitness as HKT>::Type<B>
+    where
+        Func: FnOnce(A) -> <OptionWitness as HKT>::Type<B>,
+    {
+        m_a.and_then(f)
+    }
+}
+
+// Manual implementation of Functor for ResultWitness
+impl<E> Functor<ResultWitness<E>> for ResultWitness<E>
+where
+    E: 'static,
+{
+    fn fmap<A, B, Func>(
+        m_a: <ResultWitness<E> as HKT2<E>>::Type<A>,
+        f: Func,
+    ) -> <ResultWitness<E> as HKT2<E>>::Type<B>
+    where
+        Func: FnOnce(A) -> B,
+    {
+        m_a.map(f)
+    }
+}
+
+// Manual implementation of Monad for ResultWitness
+impl<E> Monad<ResultWitness<E>> for ResultWitness<E>
+where
+    E: 'static,
+{
+    fn pure<T>(value: T) -> <ResultWitness<E> as HKT2<E>>::Type<T> {
+        Ok(value)
+    }
+
+    fn bind<A, B, Func>(
+        m_a: <ResultWitness<E> as HKT2<E>>::Type<A>,
+        f: Func,
+    ) -> <ResultWitness<E> as HKT2<E>>::Type<B>
+    where
+        Func: FnOnce(A) -> <ResultWitness<E> as HKT2<E>>::Type<B>,
+    {
+        m_a.and_then(f)
+    }
+}