Merge pull request #395 from marvin-hansen/main

feat(deep_causality_haft): Implemented Unbound HKTs, N-Arity traits, and more algebra traits

Author: marvin-hansen

deep_causality_haft/Cargo.toml

@@ -6,35 +6,73 @@ rust-version = { workspace = true }
 license = { workspace = true }
 
 repository = "https://github.com/deepcausality/deep_causality.rs"
-authors = ["Marvin Hansen <marvin.hansen@gmail.com>", ]
+authors = ["Marvin Hansen <marvin.hansen@gmail.com>"]
 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/**/*"]
+exclude = [
+    "*.bazel",
+    "*/*.bazel",
+    "*.bazel.*",
+    "BUILD",
+    "BUILD.bazel",
+    "MODULE.bazel",
+    ".bazelignore",
+    ".bazelrc",
+    "tests/**/*",
+]
 
 
 [dependencies.deep_causality_num]
 path = "../deep_causality_num"
 version = "0.1"
 
 [[example]]
-name = "haft_comonad_example"
-path = "examples/comonad_haft.rs"
+name = "haft_applicative"
+path = "examples/applicative.rs"
 
 [[example]]
-name = "haft_effect_system_example"
-path = "examples/effect_system_example.rs"
+name = "haft_foldable"
+path = "examples/foldable.rs"
+
+[[example]]
+name = "haft_monad"
+path = "examples/monad.rs"
+
+[[example]]
+name = "haft_functor"
+path = "examples/functor.rs"
+
+[[example]]
+name = "haft_comonad"
+path = "examples/comonad.rs"
+
+[[example]]
+name = "haft_traversable"
+path = "examples/traversable.rs"
+
+[[example]]
+name = "haft_adjunction"
+path = "examples/adjunction.rs"
+
+[[example]]
+name = "haft_parametric_monad"
+path = "examples/parametric_monad.rs"
+
+[[example]]
+name = "haft_bifunctor"
+path = "examples/bifunctor.rs"
 
 [[example]]
-name = "haft_simple_example"
-path = "examples/simple_haft.rs"
+name = "haft_profunctor"
+path = "examples/profunctor.rs"
 
 [[example]]
-name = "haft_functor_example"
-path = "examples/functor_haft.rs"
+name = "haft_effect_system_example"
+path = "examples/effect_system.rs"
 
 [[example]]
-name = "haft_traversable_example"
-path = "examples/traversable_haft.rs"
+name = "haft_unbound_example"
+path = "examples/unbound_haft.rs"

deep_causality_haft/README.md

@@ -89,7 +89,7 @@ fn main() {
 }
 ```
 
-When you run [the example ](/deep_causality_haft/examples/functor_haft.rs)via:
+When you run the example via:
 
 `cargo run  --example haft_functor_example`
 
@@ -256,7 +256,7 @@ use deep_causality_haft::{Effect5, MonadEffect5, HKT5};
     println!("Sequenced outcome: {:?}", current_effect.value);
 ```
 
-When you run [the example ](/deep_causality_haft/examples/effect_system_example.rs)via:
+When you run the example via:
 
 `cargo run  --example haft_effect_system_example`
 
@@ -321,6 +321,53 @@ Here's a breakdown of how it works:
    robust and predictable code.
 
 
+## Unbound HKTs & Functional Traits (Arity 2-5)
+
+This crate also supports "Unbound" Higher-Kinded Types, where all generic parameters are free to vary. This enables advanced functional patterns from Category Theory that are crucial for complex systems modeling.
+
+### Unbound HKT Traits
+
+*   **`HKT2Unbound` - `HKT5Unbound`**: Base traits for multi-arity type constructors (e.g., `Result<A, B>`, `(A, B, C)`).
+*   **`Bifunctor`**: Maps over both types of a binary constructor simultaneously.
+    *   *Usage*: Evolving a coupled system (e.g., `(Metric, Plasma)`) where both components change type.
+*   **`Profunctor`**: Contravariant input, Covariant output.
+    *   *Usage*: Adapters, Optics, and State Machines where you pre-process input and post-process output.
+*   **`Adjunction`**: Defines a dual relationship between two functors ($L \dashv R$).
+    *   *Usage*: Conservation laws, optimization (Primal/Dual), and Galois connections.
+*   **`ParametricMonad`**: A Monad where the state type changes (Indexed Monad).
+    *   *Usage*: Modeling state transitions (e.g., `Solid -> Liquid -> Gas`) or protocol state machines.
+*   **`Promonad`**: Models interaction or fusion of contexts.
+    *   *Usage*: Tensor products, force calculations (merging fields), and quantum entanglement.
+*   **`RiemannMap`**: Models curvature and scattering (Arity 4).
+    *   *Usage*: General Relativity (Curvature Tensor), Particle Physics (Scattering Matrices).
+*   **`CyberneticLoop`**: Models a complete feedback control loop (Arity 5).
+    *   *Usage*: Autonomous agents (OODA Loop), Control Theory, and Error Correction.
+
+### Example: Bifunctor
+
+```rust
+use deep_causality_haft::{Bifunctor, HKT2Unbound};
+
+struct ResultWitness;
+impl HKT2Unbound for ResultWitness {
+    type Type<A, B> = Result<A, B>;
+}
+
+impl Bifunctor<ResultWitness> for ResultWitness {
+    fn bimap<A, B, C, D, F1, F2>(fab: Result<A, B>, mut f1: F1, mut f2: F2) -> Result<C, D>
+    where F1: FnMut(A) -> C, F2: FnMut(B) -> D {
+        match fab {
+            Ok(a) => Ok(f1(a)),
+            Err(b) => Err(f2(b)),
+        }
+    }
+}
+
+// Usage
+let res: Result<i32, &str> = Ok(10);
+let new_res = ResultWitness::bimap(res, |x| x * 2.0, |e| e.len()); // Result<f64, usize>
+```
+
 ## 👨‍💻👩‍💻 Contribution
 
 Contributions are welcomed especially related to documentation, example code, and fixes.

deep_causality_haft/examples/adjunction.rs

@@ -0,0 +1,83 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+
+// ============================================================================
+// Adjunction: Global Configuration Access
+// ============================================================================
+
+// ENGINEERING VALUE:
+// Adjunctions describe a relationship between two functors: Left (L) and Right (R).
+// A classic example is (Writer -| Reader) or (Product -| Exponential).
+//
+// Here we demonstrate the "Reader Adjunction" pattern (Product -| Reader).
+// It allows us to convert a function that takes a Context (Reader) into a
+// simple value pair (Product), and vice versa.
+//
+// Practical Use: "Currying" configuration.
+// Instead of passing `Config` to every function, we can "adjunct" the function
+// to lock in the config, producing a standalone value.
+
+fn main() {
+    println!("=== DeepCausality HKT: Adjunction Pattern ===\n");
+    println!("--- Reader/Writer Duality ---");
+    println!("(Demonstration of concept)");
+
+    // Scenario: We have a function that fetches data given a Config and an ID.
+    // fetch_data: (Config, i32) -> String
+    let fetch_data = |cfg: Config, id: i32| -> String {
+        format!("Data for ID {} using Key {}", id, cfg.api_key)
+    };
+
+    // We want to "bake in" the ID first, creating a reusable "Reader" that just needs Config.
+    // We use the Right Adjunct logic manually here since Rust closures are tricky.
+
+    let id_to_fetch = 42;
+    let reader = move |cfg: Config| fetch_data(cfg, id_to_fetch);
+
+    // Now 'reader' is a function Config -> String.
+    // We can pass this 'reader' around to a component that holds the Config.
+
+    let my_config = Config {
+        api_key: "SECRET_KEY".to_string(),
+    };
+
+    let result = reader(my_config);
+    println!("Adjunction Result: {}", result);
+}
+
+struct Config {
+    api_key: String,
+}
+
+// Mock Adjunction Implementation for demonstration
+#[allow(dead_code)]
+struct ConfigAdjunction;
+
+#[allow(dead_code)]
+impl ConfigAdjunction {
+    // Left Adjunct: (Config, A) -> B  ===>  A -> (Config -> B)
+    fn left_adjunct<A, B, F>(f: F) -> impl Fn(A) -> Box<dyn Fn(Config) -> B>
+    where
+        A: Clone + 'static,
+        F: Fn(Config, A) -> B + Clone + 'static,
+    {
+        move |a: A| {
+            let f = f.clone();
+            let a = a.clone();
+            Box::new(move |cfg: Config| f(cfg, a.clone()))
+        }
+    }
+
+    // Right Adjunct: A -> (Config -> B)  ===>  (Config, A) -> B
+    fn right_adjunct<A, B, F>(f: F) -> impl Fn(Config, A) -> B
+    where
+        F: Fn(A) -> Box<dyn Fn(Config) -> B>,
+    {
+        move |cfg: Config, a: A| {
+            let reader = f(a);
+            reader(cfg)
+        }
+    }
+}

deep_causality_haft/examples/applicative.rs

@@ -0,0 +1,87 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+
+use deep_causality_haft::{Functor, OptionWitness};
+
+// ============================================================================
+// Domain: E-Commerce Order Processing
+// ============================================================================
+
+fn main() {
+    println!("=== DeepCausality HKT: Applicative Pattern ===\n");
+
+    // ------------------------------------------------------------------------
+    // Applicative: Independent Validation
+    //
+    // ENGINEERING VALUE:
+    // When validating a form, you often want to collect ALL errors, not just the first one.
+    // Or you want to combine multiple independent results (e.g., parallel API calls).
+    //
+    // Applicative (`apply`) allows you to combine values inside a context (Result/Option)
+    // independent of each other.
+    // ------------------------------------------------------------------------
+    println!("--- Independent Validation ---");
+
+    let validate_id = |id: &str| -> Option<String> {
+        if id.len() > 3 {
+            Some(id.to_string())
+        } else {
+            None
+        }
+    };
+
+    let validate_qty = |qty: u32| -> Option<u32> { if qty > 0 { Some(qty) } else { None } };
+
+    // We want to create an OrderItem ONLY if both ID and Qty are valid.
+    // Applicative style: pure(constructor).apply(id).apply(qty)
+
+    let valid_id = validate_id("item_123");
+    let _valid_qty = validate_qty(5);
+    let price = 10.0;
+
+    // Note: Rust's type system makes currying a bit verbose, so we often use helper macros or
+    // explicit closures. Here we show the raw `apply` mechanism.
+    // We lift a closure that takes (String, u32) -> OrderItem
+    let constructor = |id: String| {
+        move |qty: u32| OrderItem {
+            id,
+            price,
+            quantity: qty,
+        }
+    };
+
+    // Step 1: Lift constructor into Option
+    // Option<Fn(String) -> Fn(u32) -> OrderItem>
+    // Using OptionWitness::fmap for step 1
+    let _partial_constructor = OptionWitness::fmap(valid_id, constructor);
+
+    // Now we have Option<Fn(u32) -> OrderItem>. We need to apply Option<u32>.
+    // OptionWitness::apply expects Option<Fn(A) -> B> and Option<A>.
+
+    let config_host = Some("localhost".to_string());
+    let config_port = 8080; // Directly use value to avoid unwrap warning
+
+    // We want to combine them into a string "host:port"
+    let combine = |host: String| move |port: i32| format!("{}:{}", host, port);
+
+    let partial = OptionWitness::fmap(config_host, combine);
+    // partial is Some(Fn(i32) -> String)
+
+    // We need to cast/coerce the closure type for `apply` to work generically,
+    // which is hard in stable Rust without boxing.
+    // So we'll simulate `apply` behavior for the example's clarity.
+
+    if let Some(f) = partial {
+        let result = f(config_port); // Simulating apply
+        println!("Applicative Result: {}", result);
+    }
+}
+
+#[derive(Debug, Clone, PartialEq)]
+struct OrderItem {
+    id: String,
+    price: f64,
+    quantity: u32,
+}