System Architecture & EPP
Relevant source files
The following files were used as context for generating this wiki page:
- openspec/changes/archive/2026-05-15-rebuild-website-astro/specs/documentation-site/spec.md
- openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md
- openspec/changes/archive/2026-05-15-rebuild-website-astro/tasks.md
- openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md
- openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md
- website/web/DESIGN.md
Introduction
The Effect Propagation Process (EPP) represents the conceptual and technical core of the DeepCausality framework, moving beyond static causal modeling into the realm of Dynamic Causality. The system architecture is designed as a multi-crate Rust monorepo that implements complex causal structures including Causaloids, Context hypergraphs, and Effect Ethos. The EPP serves as the formal foundation for how effects compose and propagate through these structures, governed by functional programming principles such as the Causal Monad and Higher-Kinded Types (HKT).
Sources: openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md, openspec/changes/archive/2026-05-15-rebuild-website-astro/specs/documentation-site/spec.md
The architecture transition from "hypergeometric computational causality" to "dynamic causality" reflects a shift toward modeling active, mutable causal rules in real-world engineering fields such as aerospace, sensor monitoring, and biomedicine. The EPP is documented extensively through a six-volume monograph covering metaphysics, formalization, ontology, epistemology, and teleology of effect propagation.
Sources: openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md, openspec/changes/archive/2026-05-15-rebuild-website-astro/specs/documentation-site/spec.md
Core Architectural Components
The system is structured around several primary pillars that define the EPP and dynamic causality framework.
1. Causaloid
The Causaloid is the fundamental unit of causality within the system. It encapsulates causal logic and state, allowing for the construction of complex causal chains. In the getting-started guides, developers are introduced to the EPP by first constructing and evaluating a Causaloid.
Sources: openspec/changes/archive/2026-05-15-rebuild-website-astro/specs/documentation-site/spec.md:65-68, openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md
2. Context (Hypergraph)
Context provides the environment in which Causaloids operate. It is implemented as a hypergraph structure that allows for dynamic and mutable relationships between causal elements.
Sources: openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md
3. Effect Ethos
Effect Ethos represents the set of rules or governing principles that determine how effects are processed and validated within a specific context or causal model.
Sources: openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md
4. Causal Monad & HKT
The functional core of effect propagation is built upon the Causal Monad (implemented in deep_causality_core::types::causal_monad). It utilizes Higher-Kinded Types (HKT) to express propagation generically across different causal types.
Sources: openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md, openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md
Component Relationship Diagram
The following diagram illustrates how the core pillars interact within the EPP framework.
The diagram shows the hierarchy where the Causal Monad and HKT form the EPP logic, which then drives the Propagating Effect within Causaloids, mediated by Context and Ethos.
Sources: openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md, openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md
Effect Propagation Formalization
The EPP is formalized through specific axioms and processes that govern how data transforms into causal insights.
The Causal Monad Axiom
The system's dynamic causality is anchored on the monad axiom:
m2 = m1 >>= f
This represents the binding of a causal state (m1) to a function (f) to produce a new causal state (m2).
Sources: openspec/changes/archive/2026-05-15-rebuild-website-astro/tasks.md:129-130
Propagation Modalities
The framework supports three distinct modalities of causality:
- Static: Fixed causal relationships.
- Dynamic: Relationships that change based on context or time.
- Emergent: Relationships that arise from complex interactions within the hypergraph.
Sources: openspec/changes/archive/2026-05-15-rebuild-website-astro/tasks.md:129-130
HKT Implementation Detail
Because Rust does not natively support HKT, the system uses a "Witness" pattern to implement Functor, Applicative, and Monad traits. For example, Uncertain<T> computations are redesigned using a ConstTree to allow for symbolic representation and monadic binding.
This diagram represents the structural implementation of HKT for uncertain causal types using persistent tree structures.
Sources: openspec/changes/archive/spec-kit-old/008-hkt-uncertain-specs/plan.md
Causal Discovery Pipeline (CDL)
The Causal Discovery Language (CDL) provides a Domain Specific Language (DSL) to streamline the process of moving from raw data to the EPP.
Pipeline Workflow
The pipeline uses a typestate-builder pattern to ensure semantic correctness at compile time.
| Step | Component | Description |
|---|---|---|
| 1. Start | ProcessDataLoader | Loads data from CSV or Parquet into a CausalTensor. |
| 2. Feature Selection | mRMR | Maximum Relevance Minimum Redundancy algorithm identifies key variables. |
| 3. Discovery | SURD | Run Causal Discovery using the SURD algorithm. |
| 4. Analysis | ResultAnalyzer | Recommends how to map results to Causaloid structures. |
| 5. Finalize | ResultFormatter | Formats results for consumption (e.g., Console, PDF). |
Sources: openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md
Pipeline Sequence
The following sequence diagram shows the data flow through a CDL pipeline.
The sequence demonstrates the transition from raw data storage to a refined causal recommendation.
Sources: openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md
Monograph: The Six Volumes of EPP
The EPP is theoretically grounded in a six-volume monograph. This research is published as canonical LaTeX sources and represented in the system architecture through MDX overviews and PDF downloads.
| Volume | Title | Focus |
|---|---|---|
| I | Preprint_EPP | General overview and foundations. |
| II | Preprint_EPP_Metaphysics | Philosophical basis of dynamic causality. |
| III | Preprint_EPP_Formalization | Mathematical and logic formalisms. |
| IV | Preprint_EPP_Ontology | Structure and classification of causal entities. |
| V | Preprint_EPP_Epistemology | How causal knowledge is acquired and verified. |
| VI | Preprint_EPP_Teleology | Goal-oriented causal processes. |
Sources: openspec/changes/archive/2026-05-15-rebuild-website-astro/specs/documentation-site/spec.md:46-55
Conclusion
The system architecture of DeepCausality is a robust implementation of the Effect Propagation Process. By combining high-level functional abstractions (Monads, HKT) with practical causal discovery pipelines (CDL) and a hypergraph-based context, the project enables sophisticated modeling of dynamic causality. The integration of theoretical research from the six-volume EPP monograph directly into the software crates ensures that the implementation remains grounded in a formal causal framework.