mycorrhizal 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

mycorrhizal/{enoki → septum}/core.py

@@ -1,27 +1,27 @@
 #!/usr/bin/env python3
 """
-Enoki - Asyncio Finite State Machine Framework
+Septum - Asyncio Finite State Machine Framework
 
 A decorator-based DSL for defining and executing state machines with support for
 asyncio, timeouts, message passing, and hierarchical state composition.
 
 Usage:
-    from mycorrhizal.enoki.core import enoki, StateMachine, LabeledTransition
+    from mycorrhizal.septum.core import septum, StateMachine, LabeledTransition
     from enum import Enum, auto
 
-    @enoki.state()
+    @septum.state()
     def IdleState():
         class Events(Enum):
             START = auto()
             QUIT = auto()
 
-        @enoki.on_state
+        @septum.on_state
         async def on_state(ctx):
             if ctx.msg == "start":
                 return Events.START
             return None
 
-        @enoki.transitions
+        @septum.transitions
         def transitions():
             return [
                 LabeledTransition(Events.START, ProcessingState),
@@ -68,7 +68,7 @@ import asyncio
 from pathlib import Path
 from asyncio import PriorityQueue
 from dataclasses import dataclass, field
-from enum import Enum, auto, IntEnum
+from enum import Enum, auto, IntEnum  # noqa: F401 - auto used in docstring examples
 from typing import (
     Any,
     Callable,
@@ -79,17 +79,42 @@ from typing import (
     Awaitable,
     TypeVar,
     Generic,
+    Tuple,
+    Type,
+)
+from weakref import WeakKeyDictionary  # noqa: F401 - reserved for future use
+
+from mycorrhizal.common.wrappers import create_view_from_protocol
+from mycorrhizal.common.compilation import (
+    _get_compiled_metadata,
+    _clear_compilation_cache,
 )
-from functools import cache
 
 
 T = TypeVar('T')
 
 
 # ============================================================================
-# Interface Integration Helper
+# Interface View Caching
 # ============================================================================
 
+# Cache for interface views to avoid repeated creation
+# Uses (id(blackboard_instance), interface_type) as cache key
+# This is safe because:
+# 1. id() is unique per object instance (memory address)
+# 2. Different blackboard instances get separate cache entries (correct isolation)
+# 3. Same blackboard instance shared across FSMs gets cached views (correct sharing)
+# 4. Cache is module-level global, cleared between tests via _clear_interface_view_cache()
+_interface_view_cache: Dict[Tuple[int, Type], Any] = {}
+
+
+def _clear_interface_view_cache() -> None:
+    """Clear the interface view cache. Useful for testing."""
+    global _interface_view_cache
+    _interface_view_cache.clear()
+    # Also clear the compilation cache from common module
+    _clear_compilation_cache()
+
 
 def _create_interface_view_for_context(context: SharedContext, handler: Callable) -> SharedContext:
     """
@@ -98,41 +123,57 @@ def _create_interface_view_for_context(context: SharedContext, handler: Callable
     This enables type-safe, constrained access to blackboard state based on
     interface definitions created with @blackboard_interface.
 
+    The function signature can use an interface type:
+        async def on_state(ctx: SharedContext[MyInterface]):
+            # ctx.common is automatically a constrained view
+            return Events.DONE
+
     Args:
         context: The SharedContext object
         handler: The state handler function to check for interface type hints
 
     Returns:
-        Either the original context or a new context with constrained common field
+        The same context object with context.common potentially updated to a constrained view
+
+    Raises:
+        TypeError: If handler is not callable or type hints are malformed
+        AttributeError: If type hints reference undefined types
+
+    Note:
+        Uses id() for cache key which is safe because id() is unique per object instance.
+
+        Mutates context.common in-place which is safe because:
+        1. ConstrainedView wraps the underlying blackboard and forwards mutations to it
+        2. All interface views for the same blackboard share the same underlying state
+        3. Mutations through interface views PERSIST and are visible to subsequent states (this is intentional!)
+        4. Each handler call creates a fresh interface view wrapping self.context.common
+        5. Different handlers can have different interfaces, but all mutations go to the same blackboard
+        6. Readonly enforcement happens in ConstrainedView.__setattr__, not via context isolation
     """
-    from typing import get_type_hints
-
-    try:
-        sig = inspect.signature(handler)
-        params = list(sig.parameters.values())
-
-        # Check first parameter (should be SharedContext)
-        if params and params[0].name == 'ctx':
-            ctx_type = get_type_hints(handler).get('ctx')
-
-            # If type hint exists and is a generic SharedContext with interface
-            if ctx_type and hasattr(ctx_type, '__args__'):
-                # Extract the type argument from SharedContext[InterfaceType]
-                interface_type = ctx_type.__args__[0]
-
-                # If it has interface metadata, create constrained view
-                if hasattr(interface_type, '_readonly_fields'):
-                    from mycorrhizal.common.wrappers import create_view_from_protocol
-                    from dataclasses import replace
-
-                    # Create constrained view of common
-                    constrained_common = create_view_from_protocol(context.common, interface_type)
+    # Get compiled metadata (uses EAFP pattern internally)
+    # Raises specific exceptions if compilation fails
+    metadata = _get_compiled_metadata(handler)
+
+    # If handler has interface type hint, create constrained view
+    if metadata.has_interface and metadata.interface_type:
+        # Use id() as cache key for singleton instance caching
+        cache_key = (id(context.common), metadata.interface_type)
+
+        # Check cache
+        if cache_key in _interface_view_cache:
+            constrained_common = _interface_view_cache[cache_key]
+        else:
+            # Create view
+            constrained_common = create_view_from_protocol(
+                context.common,
+                metadata.interface_type,
+                readonly_fields=metadata.readonly_fields
+            )
+            # Cache for reuse
+            _interface_view_cache[cache_key] = constrained_common
 
-                    # Return new context with constrained common
-                    return replace(context, common=constrained_common)
-    except Exception:
-        # If anything goes wrong with type inspection, fall back to original context
-        pass
+        # Update context.common in-place (safe, see Note above)
+        context.common = constrained_common
 
     return context
 
@@ -152,7 +193,7 @@ class StateConfiguration:
             transition (returning None from on_state is allowed).
 
     Example:
-        @enoki.state(config=StateConfiguration(timeout=5.0, retries=3))
+        @septum.state(config=StateConfiguration(timeout=5.0, retries=3))
         def MyState():
             # State with timeout and retry handling
             pass
@@ -180,7 +221,7 @@ class SharedContext(Generic[T]):
     Type parameter T represents the type of the 'common' field for type safety.
 
     Example:
-        @enoki.on_state
+        @septum.on_state
         async def on_state(ctx: SharedContext):
             # Access shared data
             counter = ctx.common.get("counter", 0)
@@ -428,6 +469,23 @@ def get_all_states() -> Dict[str, StateSpec]:
     return _state_registry.copy()
 
 
+def _clear_state_registry() -> None:
+    """Clear the global state registry. Useful for testing.
+
+    This function should be called in test fixtures to ensure tests
+    don't interfere with each other through shared state registrations.
+
+    Example:
+        @pytest.fixture(autouse=True)
+        def clear_registries():
+            _clear_state_registry()
+            yield
+            _clear_state_registry()
+    """
+    global _state_registry
+    _state_registry.clear()
+
+
 # ============================================================================
 # StateRegistry - Validation and Resolution
 # ============================================================================
@@ -455,6 +513,7 @@ class StateRegistry:
     - Validating all states in a state machine
     - Getting transition mappings for states
     - Detecting circular references and invalid transitions
+    - Per-instance state registries for better modularity
     """
 
     def __init__(self):
@@ -503,16 +562,14 @@ class StateRegistry:
         if state_name in self._state_cache and not validate_only:
             return self._state_cache[state_name]
 
-        # Try to get from global registry
+        # Use global registry
         state = get_state(state_name)
         if state:
             if not validate_only:
                 self._state_cache[state_name] = state
             return state
 
-        # If not in global registry, we can't resolve it
-        # (In the old system, it would try dynamic imports, but with
-        # decorator-based states, everything should be pre-registered)
+        # State not found in registry
         if validate_only:
             self._validation_errors.append(
                 f"State '{state_name}' not found in registry"
@@ -609,8 +666,8 @@ class StateRegistry:
                                 f"State '{state_name}' has a push transition without a label"
                             )
                             handle_push(transition)
-                        case LabeledTransition(label, s):
-                            match s:
+                        case LabeledTransition():
+                            match transition.transition:
                                 case st if isinstance(st, StateSpec):
                                     handle_state(st)
                                 case r if isinstance(r, StateRef):
@@ -670,11 +727,21 @@ class StateRegistry:
                             discovered_states.add(resolved.name)
                             states_to_visit.append(resolved)
 
-            except Exception as e:
+            except Exception:
                 self._validation_errors.append(
                     f"Error processing transitions for state '{state_name}': {traceback.format_exc()}"
                 )
 
+        # Run PDA-specific validation
+        pda_result = self.validate_pda_properties(initial_state, error_state)
+        self._validation_errors.extend(pda_result.errors)
+        self._validation_warnings.extend(pda_result.warnings)
+
+        # Run determinism validation
+        determ_result = self.validate_determinism(initial_state, error_state)
+        self._validation_errors.extend(determ_result.errors)
+        self._validation_warnings.extend(determ_result.warnings)
+
         return ValidationResult(
             valid=len(self._validation_errors) == 0,
             errors=self._validation_errors.copy(),
@@ -707,13 +774,23 @@ class StateRegistry:
         for transition in raw_transitions:
             match transition:
                 case LabeledTransition(label, target):
+                    # Resolve target if it's a StateRef
+                    if isinstance(target, StateRef):
+                        resolved_target = self.resolve_state(target)
+                        if not resolved_target:
+                            # Can't resolve - skip this transition
+                            continue
+                        resolved = resolved_target
+                    else:
+                        resolved = target
+
                     # Use the label enum itself as the key
-                    resolved_transitions[label] = target
+                    resolved_transitions[label] = resolved
                     # Also allow lookup by label name
-                    resolved_transitions[label.name] = target
+                    resolved_transitions[label.name] = resolved
                     # Also allow lookup by label value
                     if hasattr(label, 'value'):
-                        resolved_transitions[label.value] = target
+                        resolved_transitions[label.value] = resolved
                 case s if isinstance(s, StateSpec):
                     # Direct state reference
                     resolved_transitions[s.name] = s
@@ -730,6 +807,101 @@ class StateRegistry:
         self._transition_cache[state_name] = resolved_transitions
         return resolved_transitions
 
+    def validate_pda_properties(
+        self,
+        initial_state: Union[str, StateRef, StateSpec],
+        error_state: Optional[Union[str, StateRef, StateSpec]] = None,
+    ) -> ValidationResult:
+        """Validate PDA-specific properties (stack depth, push/pop balance)."""
+        errors = []
+        warnings = []
+
+        # Get all states from global registry
+        all_states = list(get_all_states().values())
+
+        # Build a map of state name to state
+        state_map = {state.name: state for state in all_states}
+
+        for state_name, state in state_map.items():
+            transitions = state.get_transitions()
+
+            # Check for unbounded push (state pushes itself without Pop)
+            for t in transitions:
+                if isinstance(t, Push):
+                    for pushed_state in t.push_states:
+                        # Check if pushed state is the same as current state
+                        if isinstance(pushed_state, StateSpec) and pushed_state.name == state_name:
+                            # Check if there's a Pop transition
+                            has_pop = any(isinstance(tr, (Pop, type(Pop))) for tr in transitions)
+                            if not has_pop:
+                                warnings.append(
+                                    f"State '{state_name}' pushes itself without Pop. "
+                                    "This may cause unbounded stack growth."
+                                )
+
+            # Check for unreachable pop (pop without matching push)
+            has_pop = any(isinstance(t, (Pop, type(Pop))) for t in transitions)
+            if has_pop and state_name != initial_state if isinstance(initial_state, str) else state.name != (initial_state.name if isinstance(initial_state, StateSpec) else ""):
+                # Check if this state can be reached via a Push transition
+                can_be_pushed = self._check_if_state_can_be_pushed(state, state_map)
+                if not can_be_pushed:
+                    warnings.append(
+                        f"State '{state_name}' can Pop without being pushed. "
+                        "This may cause PopFromEmptyStack exception."
+                    )
+
+        return ValidationResult(
+            valid=len(errors) == 0,
+            errors=errors,
+            warnings=warnings,
+            discovered_states=set(state_map.keys()),
+        )
+
+    def _check_if_state_can_be_pushed(self, state: StateSpec, state_map: Dict[str, StateSpec]) -> bool:
+        """Check if a state can be reached via a Push transition from any other state."""
+        for other_state_name, other_state in state_map.items():
+            if other_state_name == state.name:
+                continue
+            transitions = other_state.get_transitions()
+            for t in transitions:
+                if isinstance(t, Push):
+                    for pushed_state in t.push_states:
+                        if isinstance(pushed_state, StateSpec) and pushed_state.name == state.name:
+                            return True
+        return False
+
+    def validate_determinism(
+        self,
+        initial_state: Union[str, StateRef, StateSpec],
+        error_state: Optional[Union[str, StateRef, StateSpec]] = None,
+    ) -> ValidationResult:
+        """Check that no state has multiple transitions for same event."""
+        errors = []
+
+        # Get all states from global registry
+        all_states = list(get_all_states().values())
+
+        for state in all_states:
+            event_transitions = {}
+
+            transitions = state.get_transitions()
+            for transition in transitions:
+                if isinstance(transition, LabeledTransition):
+                    event = transition.label
+                    if event in event_transitions:
+                        errors.append(
+                            f"State '{state.name}' has multiple transitions for event '{event}'. "
+                            "This creates non-deterministic behavior."
+                        )
+                    event_transitions[event] = transition
+
+        return ValidationResult(
+            valid=len(errors) == 0,
+            errors=errors,
+            warnings=[],
+            discovered_states=set(s.name for s in all_states),
+        )
+
 
 # ============================================================================
 # Message Types for StateMachine
@@ -748,13 +920,13 @@ class PrioritizedMessage:
 
 
 @dataclass
-class EnokiInternalMessage:
+class SeptumInternalMessage:
     """Base class for internal FSM messages"""
     pass
 
 
 @dataclass
-class TimeoutMessage(EnokiInternalMessage):
+class TimeoutMessage(SeptumInternalMessage):
     """Internal message for timeout events"""
     state_name: str
     timeout_id: int
@@ -793,7 +965,7 @@ class StateMachine:
     """Asyncio-native finite state machine for executing StateSpec-based states.
 
     The StateMachine manages state execution, transitions, message passing,
-    and lifecycle handling. States are defined using the @enoki.state decorator
+    and lifecycle handling. States are defined using the @septum.state decorator
     and should define on_state, on_enter, on_leave, on_timeout, or on_fail handlers.
 
     Args:
@@ -834,6 +1006,8 @@ class StateMachine:
     def __init__(
         self,
         initial_state: Union[str, StateRef, StateSpec],
+        max_queue_size: int = 1000,
+        queue_overflow_policy: str = "block",
         error_state: Optional[Union[str, StateRef, StateSpec]] = None,
         filter_fn: Optional[Callable] = None,
         trap_fn: Optional[Callable] = None,
@@ -841,8 +1015,13 @@ class StateMachine:
         common_data: Optional[Any] = None,
     ):
 
+        # Use global state registry
         self.registry = StateRegistry()
 
+        # Store queue configuration
+        self.max_queue_size = max_queue_size
+        self.queue_overflow_policy = queue_overflow_policy
+
         # The filter and trap functions
         self._filter_fn = filter_fn or (lambda x, y: None)
         self._trap_fn = trap_fn or (lambda x: None)
@@ -873,7 +1052,7 @@ class StateMachine:
         )
 
         # Asyncio-based infrastructure
-        self._message_queue = PriorityQueue()
+        self._message_queue = PriorityQueue(maxsize=max_queue_size)
         self._timeout_task = None
         self._timeout_counter = 0
         self._current_timeout_id = None
@@ -905,36 +1084,78 @@ class StateMachine:
             if message and self._filter_fn(self.context, message):
                 return
             self._send_message_internal(message)
+        except asyncio.QueueFull:
+            # Handle overflow based on policy
+            if self.queue_overflow_policy == "block":
+                # Wait for space (synchronous, so raise)
+                raise RuntimeError(
+                    "Queue full, would block. Use async send_message_async or check queue depth."
+                )
+            elif self.queue_overflow_policy == "drop_newest":
+                # Drop this message (silently)
+                pass
+            elif self.queue_overflow_policy == "fail":
+                raise RuntimeError(
+                    f"Queue full (max={self.max_queue_size}), message dropped"
+                )
+            # Note: "drop_oldest" is handled in _send_message_internal
         except Exception as e:
             self._send_message_internal(e)
 
-    def _send_message_internal(self, message: Any):
-        """Internal message sending"""
+    def _get_message_priority(self, message: Any) -> int:
+        """Get message priority for queuing."""
+        if isinstance(message, SeptumInternalMessage):
+            return self.MessagePriorities.INTERNAL_MESSAGE
+        elif isinstance(message, Exception):
+            return self.MessagePriorities.ERROR
+        else:
+            return self.MessagePriorities.MESSAGE
+
+    def _send_message_internal(self, message: Any) -> None:
+        """Internal message sending with priority handling."""
+        priority = self._get_message_priority(message)
 
         match message:
-            case _ if isinstance(message, EnokiInternalMessage):
+            case _ if isinstance(message, SeptumInternalMessage):
                 try:
                     self._message_queue.put_nowait(
-                        PrioritizedMessage(
-                            self.MessagePriorities.INTERNAL_MESSAGE, message
-                        )
+                        PrioritizedMessage(priority, message)
                     )
-                except Exception:
-                    pass  # Queue full
+                except asyncio.QueueFull:
+                    if self.queue_overflow_policy == "drop_oldest":
+                        # Drop oldest message
+                        try:
+                            self._message_queue.get_nowait()
+                            self._message_queue.put_nowait(PrioritizedMessage(priority, message))
+                        except asyncio.QueueEmpty:
+                            pass  # Queue was actually empty, race condition
+                    # Other policies handled by send_message
             case _ if isinstance(message, Exception):
                 try:
                     self._message_queue.put_nowait(
-                        PrioritizedMessage(self.MessagePriorities.ERROR, message)
+                        PrioritizedMessage(priority, message)
                     )
-                except Exception:
-                    pass
+                except asyncio.QueueFull:
+                    if self.queue_overflow_policy == "drop_oldest":
+                        # Drop oldest message
+                        try:
+                            self._message_queue.get_nowait()
+                            self._message_queue.put_nowait(PrioritizedMessage(priority, message))
+                        except asyncio.QueueEmpty:
+                            pass  # Queue was actually empty, race condition
             case _:
                 try:
                     self._message_queue.put_nowait(
-                        PrioritizedMessage(self.MessagePriorities.MESSAGE, message)
+                        PrioritizedMessage(priority, message)
                     )
-                except Exception:
-                    pass
+                except asyncio.QueueFull:
+                    if self.queue_overflow_policy == "drop_oldest":
+                        # Drop oldest message
+                        try:
+                            self._message_queue.get_nowait()
+                            self._message_queue.put_nowait(PrioritizedMessage(priority, message))
+                        except asyncio.QueueEmpty:
+                            pass  # Queue was actually empty, race condition
 
     async def reset(self):
         """Reset the state machine to initial state"""
@@ -957,6 +1178,11 @@ class StateMachine:
         """Log a message"""
         print(f"[FSM] {message}")
 
+    @property
+    def queue_depth(self) -> int:
+        """Get current message queue depth."""
+        return self._message_queue.qsize()
+
     async def tick(self, timeout: Optional[Union[float, int]] = 0):
         """Process one state machine tick"""
 
@@ -969,7 +1195,7 @@ class StateMachine:
         # Validate timeout parameter
         match timeout:
             case x if x and not isinstance(x, (int, float)):
-                raise ValueError(f"Tick timeout must be None, or an int/float >= 0")
+                raise ValueError("Tick timeout must be None, or an int/float >= 0")
             case 0:
                 block = False
             case None:
@@ -1192,7 +1418,6 @@ class StateMachine:
 
     def _send_timeout_message(self, state_name: str, timeout_id: int, duration: float):
         """Internal method to send timeout messages"""
-
         timeout_msg = TimeoutMessage(state_name, timeout_id, duration)
         self._send_message_internal(timeout_msg)
 
@@ -1294,7 +1519,7 @@ class StateMachine:
 # Decorators
 # ============================================================================
 
-class _EnokiDecoratorAPI:
+class _SeptumDecoratorAPI:
     """Decorator API for defining states"""
 
     def __init__(self):
@@ -1354,19 +1579,19 @@ class _EnokiDecoratorAPI:
             Events = None
 
             for item_name, item_fn in tracked_items:
-                if hasattr(item_fn, "_enoki_on_state"):
+                if hasattr(item_fn, "_septum_on_state"):
                     on_state = item_fn
-                elif hasattr(item_fn, "_enoki_on_enter"):
+                elif hasattr(item_fn, "_septum_on_enter"):
                     on_enter = item_fn
-                elif hasattr(item_fn, "_enoki_on_leave"):
+                elif hasattr(item_fn, "_septum_on_leave"):
                     on_leave = item_fn
-                elif hasattr(item_fn, "_enoki_on_timeout"):
+                elif hasattr(item_fn, "_septum_on_timeout"):
                     on_timeout = item_fn
-                elif hasattr(item_fn, "_enoki_on_fail"):
+                elif hasattr(item_fn, "_septum_on_fail"):
                     on_fail = item_fn
-                elif hasattr(item_fn, "_enoki_transitions"):
+                elif hasattr(item_fn, "_septum_transitions"):
                     transitions = item_fn
-                elif hasattr(item_fn, "_enoki_events"):
+                elif hasattr(item_fn, "_septum_events"):
                     Events = item_fn
 
             # Validate required methods
@@ -1398,42 +1623,42 @@ class _EnokiDecoratorAPI:
 
     def on_state(self, func: Callable) -> Callable:
         """Decorator for the main state logic method"""
-        func._enoki_on_state = func
+        func._septum_on_state = func
         if self._tracking_stack:
             self._tracking_stack[-1].append((func.__name__, func))
         return func
 
     def on_enter(self, func: Callable) -> Callable:
         """Decorator for on_enter lifecycle method"""
-        func._enoki_on_enter = func
+        func._septum_on_enter = func
         if self._tracking_stack:
             self._tracking_stack[-1].append((func.__name__, func))
         return func
 
     def on_leave(self, func: Callable) -> Callable:
         """Decorator for on_leave lifecycle method"""
-        func._enoki_on_leave = func
+        func._septum_on_leave = func
         if self._tracking_stack:
             self._tracking_stack[-1].append((func.__name__, func))
         return func
 
     def on_timeout(self, func: Callable) -> Callable:
         """Decorator for on_timeout lifecycle method"""
-        func._enoki_on_timeout = func
+        func._septum_on_timeout = func
         if self._tracking_stack:
             self._tracking_stack[-1].append((func.__name__, func))
         return func
 
     def on_fail(self, func: Callable) -> Callable:
         """Decorator for on_fail lifecycle method"""
-        func._enoki_on_fail = func
+        func._septum_on_fail = func
         if self._tracking_stack:
             self._tracking_stack[-1].append((func.__name__, func))
         return func
 
     def transitions(self, func: Callable) -> Callable:
         """Decorator for declaring transitions"""
-        func._enoki_transitions = func
+        func._septum_transitions = func
         if self._tracking_stack:
             self._tracking_stack[-1].append((func.__name__, func))
         return func
@@ -1456,40 +1681,40 @@ class _EnokiDecoratorAPI:
         - You don't need external access to the Events enum
 
         Example:
-            @enoki.state()
+            @septum.state()
             def MyState():
-                @enoki.events  # Optional - makes MyState.Events accessible
+                @septum.events  # Optional - makes MyState.Events accessible
                 class Events(Enum):
                     GO = auto()
 
-                @enoki.on_state
+                @septum.on_state
                 async def on_state(ctx):
-                    return Events.GO  # Works via closure even without @enoki.events
+                    return Events.GO  # Works via closure even without @septum.events
         """
-        events_class._enoki_events = events_class
+        events_class._septum_events = events_class
         if self._tracking_stack:
             self._tracking_stack[-1].append(("Events", events_class))
         return events_class
 
     def root(self, func: Callable) -> Callable:
         """Decorator to mark a state as the initial/root state"""
-        func._enoki_is_root = True
+        func._septum_is_root = True
         return func
 
 
 # Create the decorator API instance
-enoki = _EnokiDecoratorAPI()
+septum = _SeptumDecoratorAPI()
 
 # Export decorators for convenience
-state = enoki.state
-on_state = enoki.on_state
-on_enter = enoki.on_enter
-on_leave = enoki.on_leave
-on_timeout = enoki.on_timeout
-on_fail = enoki.on_fail
-transitions = enoki.transitions
-events = enoki.events
-root = enoki.root
+state = septum.state
+on_state = septum.on_state
+on_enter = septum.on_enter
+on_leave = septum.on_leave
+on_timeout = septum.on_timeout
+on_fail = septum.on_fail
+transitions = septum.transitions
+events = septum.events
+root = septum.root
 
 
 # ============================================================================
@@ -1498,7 +1723,7 @@ root = enoki.root
 
 __all__ = [
     # Decorators
-    "enoki",
+    "septum",
     "state",
     "on_state",
     "on_enter",
@@ -1529,6 +1754,7 @@ __all__ = [
     "register_state",
     "get_state",
     "get_all_states",
+    "_clear_state_registry",
     "StateRegistry",
     "ValidationError",
     "ValidationResult",
@@ -1540,6 +1766,6 @@ __all__ = [
     "NoStateToTick",
     # Messages
     "PrioritizedMessage",
-    "EnokiInternalMessage",
+    "SeptumInternalMessage",
     "TimeoutMessage",
 ]