orca-runtime-python 0.1.16__tar.gz → 0.1.18__tar.gz

{orca_runtime_python-0.1.16 → orca_runtime_python-0.1.18}/PKG-INFO

@@ -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.16 → orca_runtime_python-0.1.18}/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-0.1.16 → orca_runtime_python-0.1.18}/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-0.1.16 → orca_runtime_python-0.1.18}/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-0.1.16 → orca_runtime_python-0.1.18}/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-0.1.16 → orca_runtime_python-0.1.18}/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 → orca_runtime_python-0.1.18}/orca_runtime_python.egg-info/PKG-INFO

@@ -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.16 → orca_runtime_python-0.1.18}/orca_runtime_python.egg-info/SOURCES.txt

@@ -18,4 +18,5 @@ tests/test_guards.py
 tests/test_ignored_events.py
 tests/test_md_parser.py
 tests/test_parallel.py
+tests/test_production_hardening.py
 tests/test_snapshot_restore.py

{orca_runtime_python-0.1.16 → orca_runtime_python-0.1.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "orca-runtime-python"
-version = "0.1.16"
+version = "0.1.18"
 description = "Python async runtime for Orca state machines"
 readme = "README.md"
 license = {text = "Apache-2.0"}

orca_runtime_python-0.1.18/tests/test_production_hardening.py

@@ -0,0 +1,391 @@
+"""Tests for production hardening gaps (Gap 1-4, M-1, M-2, M-3)."""
+
+import asyncio
+import warnings
+from typing import Any
+from orca_runtime_python.parser import parse_orca_md, ParseError
+from orca_runtime_python.machine import OrcaMachine, MachineNotActiveError
+from orca_runtime_python.persistence import PersistenceAdapter, AsyncPersistenceAdapter
+from orca_runtime_python.bus import EventBus
+
+
+SIMPLE_MD = """# machine simple
+## state idle [initial]
+## state done [final]
+## transitions
+| Source | Event | Guard | Target | Action |
+|--------|-------|-------|--------|--------|
+| idle | GO | | done | |
+"""
+
+VERSIONED_MD = """# machine versioned
+- version: 2.0.0
+## state idle [initial]
+## state done [final]
+## transitions
+| Source | Event | Guard | Target | Action |
+|--------|-------|-------|--------|--------|
+| idle | GO | | done | |
+"""
+
+
+# ── Gap 1: snapshot includes machine name and definition_version ──────────────
+
+async def _test_snapshot_includes_machine_name():
+    bus = EventBus()
+    defn = parse_orca_md(SIMPLE_MD)
+    machine = OrcaMachine(defn, event_bus=bus)
+    await machine.start()
+    snap = machine.snapshot()
+    assert snap["machine"] == "simple", f"Expected 'simple', got '{snap['machine']}'"
+    assert "definition_version" in snap, "Expected definition_version in snapshot"
+    assert snap["definition_version"] == "0.1.0"
+
+
+def test_snapshot_includes_machine_name():
+    asyncio.run(_test_snapshot_includes_machine_name())
+
+
+# ── Gap 2: send() before start() raises MachineNotActiveError ────────────────
+
+async def _test_send_before_start_raises():
+    bus = EventBus()
+    defn = parse_orca_md(SIMPLE_MD)
+    machine = OrcaMachine(defn, event_bus=bus)
+    raised = False
+    try:
+        await machine.send("GO")
+    except MachineNotActiveError:
+        raised = True
+    assert raised, "Expected MachineNotActiveError when send() called before start()"
+
+
+async def _test_send_after_stop_raises():
+    bus = EventBus()
+    defn = parse_orca_md(SIMPLE_MD)
+    machine = OrcaMachine(defn, event_bus=bus)
+    await machine.start()
+    await machine.stop()
+    raised = False
+    try:
+        await machine.send("GO")
+    except MachineNotActiveError:
+        raised = True
+    assert raised, "Expected MachineNotActiveError when send() called after stop()"
+
+
+async def _test_send_after_start_does_not_raise():
+    bus = EventBus()
+    defn = parse_orca_md(SIMPLE_MD)
+    machine = OrcaMachine(defn, event_bus=bus)
+    await machine.start()
+    result = await machine.send("GO")
+    assert result.taken is True
+
+
+def test_send_before_start_raises():
+    asyncio.run(_test_send_before_start_raises())
+
+def test_send_after_stop_raises():
+    asyncio.run(_test_send_after_stop_raises())
+
+def test_send_after_start_does_not_raise():
+    asyncio.run(_test_send_after_start_does_not_raise())
+
+
+# ── Gap 3: AsyncPersistenceAdapter + auto-save + load_or_start ───────────────
+
+class _InMemorySync:
+    """Synchronous in-memory persistence for testing."""
+    def __init__(self):
+        self._store: dict[str, Any] = {}
+        self.save_calls: int = 0
+
+    def save(self, run_id: str, snapshot: dict[str, Any]) -> None:
+        self._store[run_id] = snapshot
+        self.save_calls += 1
+
+    def load(self, run_id: str) -> dict[str, Any] | None:
+        return self._store.get(run_id)
+
+    def exists(self, run_id: str) -> bool:
+        return run_id in self._store
+
+
+class _InMemoryAsync:
+    """Async in-memory persistence for testing."""
+    def __init__(self):
+        self._store: dict[str, Any] = {}
+        self.save_calls: int = 0
+
+    async def save(self, run_id: str, snapshot: dict[str, Any]) -> None:
+        self._store[run_id] = snapshot
+        self.save_calls += 1
+
+    async def load(self, run_id: str) -> dict[str, Any] | None:
+        return self._store.get(run_id)
+
+    async def exists(self, run_id: str) -> bool:
+        return run_id in self._store
+
+
+async def _test_auto_save_sync_persistence():
+    bus = EventBus()
+    defn = parse_orca_md(SIMPLE_MD)
+    p = _InMemorySync()
+    machine = OrcaMachine(defn, event_bus=bus, persistence=p, run_id="run-1")
+    await machine.start()
+    assert p.save_calls == 0, "No save before first transition"
+    await machine.send("GO")
+    assert p.save_calls == 1, "Expected one save after transition"
+    snap = p.load("run-1")
+    assert snap is not None
+    assert snap["machine"] == "simple"
+    assert snap["state"] == "done"
+
+
+async def _test_auto_save_async_persistence():
+    bus = EventBus()
+    defn = parse_orca_md(SIMPLE_MD)
+    p = _InMemoryAsync()
+    machine = OrcaMachine(defn, event_bus=bus, persistence=p, run_id="run-1")
+    await machine.start()
+    await machine.send("GO")
+    assert p.save_calls == 1, "Expected one save after transition"
+    snap = await p.load("run-1")
+    assert snap is not None
+    assert snap["state"] == "done"
+
+
+async def _test_load_or_start_fresh():
+    bus = EventBus()
+    defn = parse_orca_md(SIMPLE_MD)
+    p = _InMemorySync()
+    machine = OrcaMachine(defn, event_bus=bus, persistence=p, run_id="run-fresh")
+    await machine.load_or_start()
+    assert machine.is_active
+    assert machine.state.leaf() == "idle"
+
+
+async def _test_load_or_start_resumes():
+    bus = EventBus()
+    defn = parse_orca_md(SIMPLE_MD)
+    p = _InMemorySync()
+
+    # First run: advance to done and save
+    m1 = OrcaMachine(defn, event_bus=bus, persistence=p, run_id="run-resume")
+    await m1.start()
+    await m1.send("GO")
+    assert p.exists("run-resume")
+
+    # Second run: load_or_start should resume
+    bus2 = EventBus()
+    m2 = OrcaMachine(defn, event_bus=bus2, persistence=p, run_id="run-resume")
+    await m2.load_or_start()
+    assert m2.is_active
+    assert m2.state.leaf() == "done"
+
+
+async def _test_load_or_start_no_persistence():
+    bus = EventBus()
+    defn = parse_orca_md(SIMPLE_MD)
+    machine = OrcaMachine(defn, event_bus=bus)
+    await machine.load_or_start()
+    assert machine.is_active
+    assert machine.state.leaf() == "idle"
+
+
+def test_auto_save_sync_persistence():
+    asyncio.run(_test_auto_save_sync_persistence())
+
+def test_auto_save_async_persistence():
+    asyncio.run(_test_auto_save_async_persistence())
+
+def test_load_or_start_fresh():
+    asyncio.run(_test_load_or_start_fresh())
+
+def test_load_or_start_resumes():
+    asyncio.run(_test_load_or_start_resumes())
+
+def test_load_or_start_no_persistence():
+    asyncio.run(_test_load_or_start_no_persistence())
+
+
+# ── Gap 4: version field on MachineDef; snapshot includes it; resume warns ───
+
+def test_machine_def_default_version():
+    defn = parse_orca_md(SIMPLE_MD)
+    assert defn.version == "0.1.0"
+
+
+def test_machine_def_parsed_version():
+    defn = parse_orca_md(VERSIONED_MD)
+    assert defn.version == "2.0.0"
+
+
+async def _test_resume_version_mismatch_warns():
+    bus = EventBus()
+    defn = parse_orca_md(VERSIONED_MD)
+    machine = OrcaMachine(defn, event_bus=bus)
+
+    stale_snap = {
+        "machine": "versioned",
+        "definition_version": "1.0.0",
+        "state": "idle",
+        "context": {},
+        "children": {},
+        "active_invoke": None,
+        "timestamp": 0.0,
+    }
+
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        await machine.resume(stale_snap)
+        version_warnings = [w for w in caught if issubclass(w.category, UserWarning)]
+        assert len(version_warnings) == 1
+        assert "1.0.0" in str(version_warnings[0].message)
+        assert "2.0.0" in str(version_warnings[0].message)
+
+
+async def _test_resume_matching_version_no_warn():
+    bus = EventBus()
+    defn = parse_orca_md(VERSIONED_MD)
+    machine = OrcaMachine(defn, event_bus=bus)
+
+    snap = {
+        "machine": "versioned",
+        "definition_version": "2.0.0",
+        "state": "idle",
+        "context": {},
+        "children": {},
+        "active_invoke": None,
+        "timestamp": 0.0,
+    }
+
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        await machine.resume(snap)
+        version_warnings = [w for w in caught if issubclass(w.category, UserWarning)]
+        assert len(version_warnings) == 0, "No warning expected for matching versions"
+
+
+def test_resume_version_mismatch_warns():
+    asyncio.run(_test_resume_version_mismatch_warns())
+
+def test_resume_matching_version_no_warn():
+    asyncio.run(_test_resume_matching_version_no_warn())
+
+
+# ── M-1: parser raises ParseError on structurally invalid input ──────────────
+
+def test_parse_error_no_initial_state():
+    md = """# machine bad
+## state a
+## state b
+## transitions
+| Source | Event | Guard | Target | Action |
+|--------|-------|-------|--------|--------|
+| a | GO | | b | |
+"""
+    raised = False
+    try:
+        parse_orca_md(md)
+    except ParseError as e:
+        raised = True
+        assert "no [initial] state" in str(e)
+    assert raised, "Expected ParseError for missing [initial] state"
+
+
+def test_parse_error_undefined_transition_target():
+    md = """# machine bad
+## state a [initial]
+## transitions
+| Source | Event | Guard | Target | Action |
+|--------|-------|-------|--------|--------|
+| a | GO | | nonexistent | |
+"""
+    raised = False
+    try:
+        parse_orca_md(md)
+    except ParseError as e:
+        raised = True
+        assert "nonexistent" in str(e)
+    assert raised, "Expected ParseError for undefined transition target"
+
+
+def test_parse_error_undefined_guard():
+    md = """# machine bad
+## state a [initial]
+## state b [final]
+## transitions
+| Source | Event | Guard | Target | Action |
+|--------|-------|-------|--------|--------|
+| a | GO | noSuchGuard | b | |
+"""
+    raised = False
+    try:
+        parse_orca_md(md)
+    except ParseError as e:
+        raised = True
+        assert "noSuchGuard" in str(e)
+    assert raised, "Expected ParseError for undefined guard"
+
+
+def test_parse_valid_machine_no_error():
+    defn = parse_orca_md(SIMPLE_MD)
+    assert defn.name == "simple"
+
+
+# ── M-2: TransitionResult.to_state_leaf ──────────────────────────────────────
+
+async def _test_transition_result_leaf():
+    bus = EventBus()
+    defn = parse_orca_md(SIMPLE_MD)
+    machine = OrcaMachine(defn, event_bus=bus)
+    await machine.start()
+    result = await machine.send("GO")
+    assert result.taken is True
+    assert result.to_state_leaf == "done", f"Expected 'done', got '{result.to_state_leaf}'"
+    assert result.to_state == "done"
+
+
+def test_transition_result_leaf():
+    asyncio.run(_test_transition_result_leaf())
+
+
+if __name__ == "__main__":
+    tests = [
+        ("Gap1: snapshot includes machine name", test_snapshot_includes_machine_name),
+        ("Gap2: send before start raises", test_send_before_start_raises),
+        ("Gap2: send after stop raises", test_send_after_stop_raises),
+        ("Gap2: send after start ok", test_send_after_start_does_not_raise),
+        ("Gap3: auto-save sync", test_auto_save_sync_persistence),
+        ("Gap3: auto-save async", test_auto_save_async_persistence),
+        ("Gap3: load_or_start fresh", test_load_or_start_fresh),
+        ("Gap3: load_or_start resumes", test_load_or_start_resumes),
+        ("Gap3: load_or_start no persistence", test_load_or_start_no_persistence),
+        ("Gap4: default version", test_machine_def_default_version),
+        ("Gap4: parsed version", test_machine_def_parsed_version),
+        ("Gap4: resume version mismatch warns", test_resume_version_mismatch_warns),
+        ("Gap4: resume matching version no warn", test_resume_matching_version_no_warn),
+        ("M-1: no initial state error", test_parse_error_no_initial_state),
+        ("M-1: undefined target error", test_parse_error_undefined_transition_target),
+        ("M-1: undefined guard error", test_parse_error_undefined_guard),
+        ("M-1: valid machine no error", test_parse_valid_machine_no_error),
+        ("M-2: to_state_leaf", test_transition_result_leaf),
+    ]
+
+    passed = 0
+    failed = 0
+    for name, fn in tests:
+        try:
+            fn()
+            print(f"  PASS  {name}")
+            passed += 1
+        except Exception as e:
+            print(f"  FAIL  {name}: {e}")
+            failed += 1
+
+    print(f"\n{passed} passed, {failed} failed, {passed + failed} total")
+    if failed > 0:
+        exit(1)