Causal State Machine (CSM)
Relevant source files
The following files were used as context for generating this wiki page:
The Causal State Machine (CSM) is an architectural pattern within the DeepCausality framework where state transitions are governed by causal reasoning rather than simple event-based triggers. It represents a transition from traditional finite state machines to systems where logic follows a "Cause -> Effect -> New State" flow, often incorporating ethical or normative rules to determine the permissibility of actions.
The CSM is primarily used in dynamic systems, such as sensor monitoring, where context is fluid and causal rules may evolve over time. It leverages core components of the project, specifically the Causaloid, Context, and Effect Ethos, to manage complex multi-stage causality models.
Sources: examples/csm_examples/README.md, AGENTS.md
Core Architecture
The architecture of a CSM revolves around a fundamental loop consisting of a State, a Causaloid, and an Action. Unlike standard state machines that transition based on external inputs alone, a CSM evaluates the causal validity of a transition using internal logic and external context.
The State-Causaloid-Action Loop
The execution flow within a CSM typically follows these steps:
- Sensor/Input: Data is received by the system.
- Causaloid Evaluation: The system applies causal functions to the data to determine if a specific cause is present.
- Action Execution: If the causal logic returns true, a predefined action is triggered.
- State Transition: The action results in a transition to a new system state.
The diagram shows the fundamental loop where data is processed by a Causaloid to trigger actions and transition states.
Sources: examples/csm_examples/README.md
Key Components
The CSM relies on several specialized data structures and traits to manage reasoning and execution.
Causaloid
The Causaloid is the core unit of reasoning within the CSM. It encapsulates the functional dependency required for a transition.
- Causal Function: Logic defined as $f(data) \to bool$.
- Description: A human-readable explanation of why the causal link exists.
- Weights: Used for probabilistic reasoning when certainty is not absolute.
Sources: examples/csm_examples/README.md, AGENTS.md
Contextual State
In complex implementations, state transitions depend on a global or shared context (e.g., system power levels or user permissions). The CSM supports sharing mutable data across the causal graph, typically using Arc<RwLock> to allow safe, concurrent access to a BaseContext.
Sources: examples/csm_examples/README.md
Causal Action
Actions in the CSM represent the operations performed once a causal link is verified. These are implemented as discrete types that encapsulate the logic for state modification or external system interaction.
Sources: deep_causality/src/types/csm_types/csm_action/mod.rs
Normative Reasoning (Ethical CSM)
A specialized variant of the CSM integrates Deontic Logic (Obligation, Permission, Prohibition) into the state machine. This is referred to as an "Ethical CSM" or a "Super-Ego" layer for AI agents. Before an action is executed, the system evaluates its "moral permissibility" based on normative rules.
The sequence diagram illustrates how the Ethos layer intercepts causal triggers to enforce normative rules before state transitions.
Sources: examples/csm_examples/README.md
Feature Summary Table
| Feature | Description | Relevant Component |
|---|---|---|
| Causal Reasoning | Transitions based on $f(data) \to bool$ | Causaloid |
| Context Awareness | Shared mutable data for complex aggregations | BaseContext |
| Normative Logic | Evaluation of Obligation/Prohibition | Effect Ethos |
| Action Encapsulation | Discrete logic for state changes | CSM Action |
Sources: examples/csm_examples/README.md, AGENTS.md
Implementation Examples
The project provides several implementation patterns for CSMs:
- Basic CSM: A simple monitoring system (e.g., Sensor -> Action) demonstrating the fundamental loop.
- Contextual CSM: Demonstrates sharing mutable data across the causal graph for complex state aggregations.
- Ethical CSM: Integrates normative logic to check if a causally possible action is ethically permissible.
Sources: examples/csm_examples/README.md, openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md
Summary
The Causal State Machine (CSM) provides a robust framework for building intelligent, context-aware systems where transitions are meaningful and reasoned. By separating the mathematical kernel of causality from the contextual and ethical layers, the CSM allows for high-performance execution while maintaining strict observability and operational safety. This makes it particularly suitable for advanced engineering fields like aerospace flight envelope monitoring and sensor-based autonomous systems.
Sources: examples/csm_examples/README.md, AGENTS.md