Causaloids: Singletons, Collections, Graphs

The Causaloid is a fundamental computable primitive within the DeepCausality framework, serving as a polymorphic container for causal functions. Derived from the research of Lucien Hardy, the Causaloid represents causal structure and is designed to be isomorphic across three primary forms: Singletons, Collections, and Graphs. This structural isomorphism allows recursive causal structures to be composed and evaluated without changing the underlying calling code.

Causaloids operate within an explicit environment known as the Context, and are often integrated with the Causal Monad to handle causal sequencing. While the Causal Monad focuses on the "bind" side of causal axioms (sequencing), the Causaloid focuses on the "structure" side, allowing for parallel aggregation and complex dependency modeling.

Sources: README.md:104-108, AGENTS.md:144-150, openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md:D9

Causaloid Architecture and Type System

The Causaloid is implemented as a generic struct that enforces type safety at compile-time. It moves away from runtime-polymorphic enums to a generic-based approach using PropagatingEffect<T> as a carrier for values, errors, and audit logs.

Core Components

• Causal Function (CausalFn): A type-safe function mapping an input type I to a Result<O, CausalityError>.
• Contextual Causal Function: A variant of the causal function that also accepts a reference to the global Context.
• PropagatingEffect: The carrier type used for evaluation, supporting stateless or stateful propagation.

The following diagram illustrates the relationship between a Causaloid and its internal functional components.

Structural Modalities

Causaloids are categorized into three modalities based on how they organize causal logic:

1. Singletons

A Singleton Causaloid represents a self-contained unit of causality. It wraps a single causal function that defines a specific functional dependency.

2. Collections

Causaloid Collections are used for parallel aggregation. They contain multiple constituent Causaloids and use aggregate logic to determine the final output. This is typically used for modeling multiple causes influencing a single target.

3. Graphs

Causaloid Graphs (specifically hypergraphs) are used to model cross-influencing dependencies. They represent complex networks where the output of one Causaloid may serve as the input for others, or where multiple Causaloids interact within a shared context.

Sources: README.md:122-125, openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md:Heuristics

Evaluation Flow and Registry

Evaluation within the Causaloid system is managed through a hybrid approach to maintain performance while allowing flexibility. A CausaloidRegistry provides a centralized, type-erased storage for Causaloid instances.

Evaluation Sequence

1. Input Conversion: The input PropagatingEffect value is converted into the expected generic type I.
2. Function Execution: The internal CausalFn or ContextualCausalFn is executed.
3. Output Conversion: The result is converted back into an EffectValue.
4. Automated Logging: The registry automatically appends log entries detailing the Causaloid ID, input, and output/error to the PropagatingEffect.

Integration with Causal Discovery (CDL)

Causaloids are the primary output target for the Causal Discovery Language (CDL). During the analyze step of a discovery pipeline, results from algorithms like SURD (Sum of Universal Redundancy Distributions) are mapped to specific Causaloid structures.

• Strong Synergy: Mapped to a Causaloid Collection with Aggregate Logic: All.
• Unique/Redundant Influences: Mapped to a Causaloid Collection with Aggregate Logic: Any.
• Complex Dependencies: Mapped to a CausaloidGraph.

Sources: openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md:Heuristics, README.md:Architecture

Conclusion

Causaloids provide a flexible yet rigorous framework for modeling causal structures in DeepCausality. By supporting Singletons for basic dependencies, Collections for parallel logic, and Graphs for complex networks, the system can represent diverse causal modalities—dynamic, adaptive, and emergent—while maintaining strict type safety and a verifiable audit trail through the PropagatingEffect monad.