orca-runtime-python 0.1.16__py3-none-any.whl → 0.1.18__py3-none-any.whl

orca_runtime_python/__init__.py

@@ -25,11 +25,11 @@ from .bus import (
     get_event_bus,
 )
 
-from .machine import OrcaMachine
+from .machine import OrcaMachine, MachineNotActiveError, TransitionResult
 
 from .parser import parse_orca_md, parse_orca_auto
 
-from .persistence import PersistenceAdapter, FilePersistence
+from .persistence import PersistenceAdapter, AsyncPersistenceAdapter, FilePersistence
 
 from .logging import LogSink, FileSink, ConsoleSink, MultiSink
 
@@ -55,11 +55,14 @@ __all__ = [
     "get_event_bus",
     # Machine
     "OrcaMachine",
+    "MachineNotActiveError",
+    "TransitionResult",
     # Parser
     "parse_orca_md",
     "parse_orca_auto",
     # Persistence
     "PersistenceAdapter",
+    "AsyncPersistenceAdapter",
     "FilePersistence",
     # Logging
     "LogSink",

orca_runtime_python/machine.py

@@ -34,6 +34,7 @@ from .types import (
     InvokeDef,
 )
 from .bus import EventBus, Event, EventType, get_event_bus
+from .persistence import PersistenceAdapter, AsyncPersistenceAdapter
 
 
 # Type alias for transition callback
@@ -43,12 +44,24 @@ TransitionCallback = Callable[[StateValue, StateValue], Awaitable[None]]
 ActionHandler = Callable[..., Any]  # async (dict, dict|None) -> dict|None
 
 
+class MachineNotActiveError(RuntimeError):
+    """
+    Raised when send() is called on a machine that has not been started
+    or has already been stopped.
+
+    Always indicates a caller-side sequencing error. The fix is to ensure
+    start() or resume() completes before any send() call reaches this machine.
+    """
+    pass
+
+
 @dataclass
 class TransitionResult:
     """Result of a transition attempt."""
     taken: bool
     from_state: str
     to_state: str | None = None
+    to_state_leaf: str | None = None
     guard_failed: bool = False
     error: str | None = None
 
@@ -80,6 +93,8 @@ class OrcaMachine:
         event_bus: EventBus | None = None,
         context: dict[str, Any] | None = None,
         on_transition: TransitionCallback | None = None,
+        persistence: PersistenceAdapter | AsyncPersistenceAdapter | None = None,
+        run_id: str | None = None,
     ):
         self.definition = definition
         self.event_bus = event_bus or get_event_bus()
@@ -92,6 +107,10 @@ class OrcaMachine:
         self._action_handlers: dict[str, ActionHandler] = {}
         self._timeout_task: asyncio.Task | None = None
 
+        # Persistence
+        self._persistence = persistence
+        self._run_id = run_id
+
         # Child machine management
         self._child_machines: dict[str, OrcaMachine] = {}
         self._sibling_machines: dict[str, MachineDef] | None = None
@@ -120,14 +139,16 @@ class OrcaMachine:
     def snapshot(self) -> dict[str, Any]:
         """
         Capture the current machine state as a serializable snapshot.
-        The snapshot includes state value, context, and timestamp.
-        Child machine snapshots are included.
+        The snapshot includes machine name, definition version, state value,
+        context, and timestamp. Child machine snapshots are included.
         Action handlers are NOT included — re-register them after restore.
         """
         import copy
         import time
         state_val = self._state.value
         return {
+            "machine": self.definition.name,
+            "definition_version": self.definition.version,
             "state": copy.deepcopy(state_val),
             "context": copy.deepcopy(self.context),
             "children": {k: m.snapshot() for k, m in self._child_machines.items()},
@@ -153,6 +174,29 @@ class OrcaMachine:
             for leaf in self._state.leaves():
                 self._start_timeout_for_state(leaf)
 
+    async def load_or_start(self) -> None:
+        """
+        If a snapshot exists for self._run_id, resume from it.
+        Otherwise, start fresh.
+
+        Replaces the manual pattern of checking persistence, then calling
+        resume() or start() explicitly.
+        """
+        if self._persistence and self._run_id:
+            if asyncio.iscoroutinefunction(self._persistence.exists):
+                exists = await self._persistence.exists(self._run_id)  # type: ignore[misc]
+            else:
+                exists = self._persistence.exists(self._run_id)
+            if exists:
+                if asyncio.iscoroutinefunction(self._persistence.load):
+                    snap = await self._persistence.load(self._run_id)  # type: ignore[misc]
+                else:
+                    snap = self._persistence.load(self._run_id)
+                if snap:
+                    await self.resume(snap)
+                    return
+        await self.start()
+
     async def resume(self, snap: dict[str, Any]) -> None:
         """
         Boot the machine from a saved snapshot, skipping on_entry for the
@@ -167,6 +211,18 @@ class OrcaMachine:
         if self._active:
             return
 
+        snap_version = snap.get("definition_version", "0.1.0")
+        if snap_version != self.definition.version:
+            import warnings
+            warnings.warn(
+                f"Snapshot version '{snap_version}' does not match "
+                f"machine definition version '{self.definition.version}' "
+                f"for machine '{self.definition.name}'. "
+                "The snapshot may be incompatible with the current definition.",
+                UserWarning,
+                stacklevel=2,
+            )
+
         self._state = StateValue(copy.deepcopy(snap["state"]))
         self.context = copy.deepcopy(snap["context"])
         self._active = True
@@ -310,10 +366,9 @@ class OrcaMachine:
             TransitionResult indicating what happened
         """
         if not self._active:
-            return TransitionResult(
-                taken=False,
-                from_state=str(self._state),
-                error="Machine is not active"
+            raise MachineNotActiveError(
+                f"Machine '{self.definition.name}' is not active. "
+                "Call start() or resume() before sending events."
             )
 
         # Normalize to Event, preserving the original event name
@@ -431,12 +486,25 @@ class OrcaMachine:
             }
         ))
 
+        await self._auto_save()
+
         return TransitionResult(
             taken=True,
             from_state=str(old_state),
-            to_state=str(self._state)
+            to_state=str(self._state),
+            to_state_leaf=self._state.leaf(),
         )
 
+    async def _auto_save(self) -> None:
+        """Save a snapshot if persistence and run_id are configured."""
+        if self._persistence is None or self._run_id is None:
+            return
+        snap = self.snapshot()
+        if asyncio.iscoroutinefunction(self._persistence.save):
+            await self._persistence.save(self._run_id, snap)  # type: ignore[misc]
+        else:
+            self._persistence.save(self._run_id, snap)
+
     def _find_event_type(self, event_name: str) -> EventType:
         """Map event name to EventType enum."""
         # Build a mapping from event names to event types
@@ -830,6 +898,8 @@ class OrcaMachine:
             }
         ))
 
+        await self._auto_save()
+
     def _is_event_ignored(self, event_name: str) -> bool:
         """Check if event is explicitly ignored in current state or parent states."""
         current = self._state.leaf()

orca_runtime_python/parser.py

@@ -650,9 +650,43 @@ def _map_op(op: str) -> str:
     }.get(op, "eq")
 
 
+def _validate_machine_def(defn: MachineDef) -> None:
+    """Post-parse structural validation. Raises ParseError on invalid definitions."""
+    if not defn.states:
+        raise ParseError(f"Machine '{defn.name}': no states defined.")
+    if not any(s.is_initial for s in defn.states):
+        raise ParseError(f"Machine '{defn.name}': no [initial] state.")
+    state_names = {s.name for s in defn.states}
+    # Include nested/parallel child state names
+    def _collect_names(states: list[StateDef]) -> None:
+        for s in states:
+            state_names.add(s.name)
+            if s.contains:
+                _collect_names(s.contains)
+            if s.parallel:
+                for region in s.parallel.regions:
+                    _collect_names(region.states)
+    _collect_names(defn.states)
+    for t in defn.transitions:
+        if t.source not in state_names:
+            raise ParseError(
+                f"Machine '{defn.name}': transition source '{t.source}' is not defined."
+            )
+        if t.target not in state_names:
+            raise ParseError(
+                f"Machine '{defn.name}': transition target '{t.target}' is not defined."
+            )
+        guard_ref = t.guard.lstrip("!") if t.guard else None
+        if guard_ref and guard_ref not in defn.guards:
+            raise ParseError(
+                f"Machine '{defn.name}': guard '{t.guard}' is used but not defined."
+            )
+
+
 def _parse_machine_elements(elements: list[_MdElement]) -> MachineDef:
     """Parse a single machine from already-split elements."""
     machine_name = "unknown"
+    machine_version = "0.1.0"
     context: dict[str, Any] = {}
     events: list[str] = []
     transitions: list[Transition] = []
@@ -661,6 +695,7 @@ def _parse_machine_elements(elements: list[_MdElement]) -> MachineDef:
     effects: list[EffectDef] = []
     state_entries: list[_MdStateEntry] = []
     current_state_entry: _MdStateEntry | None = None
+    in_machine_meta: bool = False
 
     i = 0
     while i < len(elements):
@@ -671,9 +706,13 @@ def _parse_machine_elements(elements: list[_MdElement]) -> MachineDef:
             if el.level == 1 and el.text.startswith("machine "):
                 machine_name = el.text[8:].strip()
                 current_state_entry = None
+                in_machine_meta = True
                 i += 1
                 continue
 
+            # Section and state headings clear machine-meta mode
+            in_machine_meta = False
+
             # Section headings
             section_name = el.text.lower()
             if section_name in ("context", "events", "transitions", "guards", "actions", "effects"):
@@ -807,6 +846,11 @@ def _parse_machine_elements(elements: list[_MdElement]) -> MachineDef:
             elif isinstance(el, _MdBulletList):
                 for item in el.items:
                     _parse_md_state_bullet(current_state_entry, item)
+        elif in_machine_meta and isinstance(el, _MdBulletList):
+            # Machine-level metadata bullets (e.g. "- version: 1.2.0")
+            for item in el.items:
+                if item.startswith("version:"):
+                    machine_version = item[len("version:"):].strip()
 
         i += 1
 
@@ -814,7 +858,7 @@ def _parse_machine_elements(elements: list[_MdElement]) -> MachineDef:
     base_level = state_entries[0].level if state_entries else 2
     states, _ = _build_md_states_at_level(state_entries, 0, base_level)
 
-    return MachineDef(
+    defn = MachineDef(
         name=machine_name,
         context=context,
         events=events,
@@ -823,7 +867,10 @@ def _parse_machine_elements(elements: list[_MdElement]) -> MachineDef:
         guards=guards,
         actions=actions,
         effects=effects,
+        version=machine_version,
     )
+    _validate_machine_def(defn)
+    return defn
 
 
 def parse_orca_md(source: str) -> MachineDef:

orca_runtime_python/persistence.py

@@ -22,7 +22,7 @@ from typing import Any, Protocol, runtime_checkable
 @runtime_checkable
 class PersistenceAdapter(Protocol):
     """
-    Protocol for Orca machine state persistence.
+    Synchronous persistence adapter. Suitable for local file I/O.
 
     Implementations must support three operations keyed by run_id:
     save, load (returns None if not found), and exists.
@@ -41,6 +41,28 @@ class PersistenceAdapter(Protocol):
         ...
 
 
+@runtime_checkable
+class AsyncPersistenceAdapter(Protocol):
+    """
+    Async persistence adapter for database and network backends.
+
+    Drop-in replacement for PersistenceAdapter when using async drivers
+    (asyncpg, aioredis, aiobotocore, etc.). OrcaMachine accepts either.
+    """
+
+    async def save(self, run_id: str, snapshot: dict[str, Any]) -> None:
+        """Persist snapshot under run_id. Overwrites any prior snapshot."""
+        ...
+
+    async def load(self, run_id: str) -> dict[str, Any] | None:
+        """Return the snapshot for run_id, or None if it doesn't exist."""
+        ...
+
+    async def exists(self, run_id: str) -> bool:
+        """Return True if a snapshot exists for run_id."""
+        ...
+
+
 class FilePersistence:
     """
     File-based persistence adapter.

orca_runtime_python/types.py

@@ -99,6 +99,7 @@ class MachineDef:
     guards: dict[str, GuardExpression] = field(default_factory=dict)
     actions: list[ActionSignature] = field(default_factory=list)
     effects: list[EffectDef] = field(default_factory=list)
+    version: str = "0.1.0"
 
 
 class GuardExpression:

{orca_runtime_python-0.1.16.dist-info → orca_runtime_python-0.1.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orca-runtime-python
-Version: 0.1.16
+Version: 0.1.18
 Summary: Python async runtime for Orca state machines
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/orca-lang/orca-lang

orca_runtime_python-0.1.18.dist-info/RECORD

@@ -0,0 +1,12 @@
+orca_runtime_python/__init__.py,sha256=wBa4uI4nU8-wafXM3rex4qHZdCqO24LtSqVGr_kSdMU,1289
+orca_runtime_python/bus.py,sha256=kCdMwm3O97wlX5hr3_aK-YkhABO7Z0M-eaYPYJAIa9g,7171
+orca_runtime_python/effects.py,sha256=eAkm2JdHSH5wUm8ZQjBf7ncgMI1iw7xq9bKi5X1AJEM,5649
+orca_runtime_python/logging.py,sha256=Bnw_PCGlMQaDbti3UNMudhj0RcOckF_7YYt_5yWatGY,4360
+orca_runtime_python/machine.py,sha256=tGcukHSCfBGKwJDxKO7vaU_dymCg9Zcpma--_KbBVvE,35972
+orca_runtime_python/parser.py,sha256=CDhdzU_GgJneBhuNPGyF45Ywa_Mk9w0VVnmQobBSyCk,32709
+orca_runtime_python/persistence.py,sha256=rjrgXDhfs3IA-c_xkQcFC4lCBlzmQtLL5lNWGu2kWu4,3330
+orca_runtime_python/types.py,sha256=Sy1FUG9kCJREQLIWytsTw6uvPdpZOeR9b3bkSvXMzd4,7259
+orca_runtime_python-0.1.18.dist-info/METADATA,sha256=ZJfXb6uyJKW-UCmedOhuXyesGPfOGQB0EXsR889GjnQ,7165
+orca_runtime_python-0.1.18.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+orca_runtime_python-0.1.18.dist-info/top_level.txt,sha256=r7KIKsP_6Io6KiMqlBoNEc4IwzaE7O3VTG-PSEu0wVY,20
+orca_runtime_python-0.1.18.dist-info/RECORD,,

orca_runtime_python-0.1.16.dist-info/RECORD

@@ -1,12 +0,0 @@
-orca_runtime_python/__init__.py,sha256=RgEnSjy5mJO_M6_3exaoWmmEK_5aXYPRMS82naWcebk,1139
-orca_runtime_python/bus.py,sha256=kCdMwm3O97wlX5hr3_aK-YkhABO7Z0M-eaYPYJAIa9g,7171
-orca_runtime_python/effects.py,sha256=eAkm2JdHSH5wUm8ZQjBf7ncgMI1iw7xq9bKi5X1AJEM,5649
-orca_runtime_python/logging.py,sha256=Bnw_PCGlMQaDbti3UNMudhj0RcOckF_7YYt_5yWatGY,4360
-orca_runtime_python/machine.py,sha256=6gccjFkD96Wpzo1VWXGTbS7gkcIzdu3w88ZTu1ey_C8,33126
-orca_runtime_python/parser.py,sha256=wu9Dlv7O7xOurRr3--lO5X-v57LkVvkbtAfcc3ez8cg,30714
-orca_runtime_python/persistence.py,sha256=lsQlvGXPelZ5u2Ote-OegtmE6Rk10fa-qj9Dkg-zl9E,2590
-orca_runtime_python/types.py,sha256=YlYcyvGHI9myHq5XDinGTjPIKadyG4kuGQvMPtU0eCo,7232
-orca_runtime_python-0.1.16.dist-info/METADATA,sha256=fTYGThJgak9lIPPP5Dq6CPWk_GXjbHNPojwfOeK7iKI,7165
-orca_runtime_python-0.1.16.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-orca_runtime_python-0.1.16.dist-info/top_level.txt,sha256=r7KIKsP_6Io6KiMqlBoNEc4IwzaE7O3VTG-PSEu0wVY,20
-orca_runtime_python-0.1.16.dist-info/RECORD,,