feat: add undo/redo support for cascade-deleted states and axes ergonomics

- object_state_registry: preserve cascade-deleted states in graveyard
  for history-enabled undo/redo support
- parametric_axes: add with_axes decorator and AxesBase class for
  more ergonomic axes metadata attachment
- tests: add test_undo_redo_cascade.py for cascade delete preservation
  and conftest.py fixtures

Author: trissim

src/objectstate/object_state_registry.py

@@ -216,9 +216,16 @@ def unregister_scope_and_descendants(cls, scope_id: Optional[str], _skip_snapsho
                 scopes_to_delete.append(key)
 
         # Delete all matching scopes and fire callbacks
+        # NOTE: Unlike plain unregister(), this is often used for hierarchical deletes.
+        # When history is enabled we must preserve removed states for time-travel (undo/redo),
+        # otherwise snapshots may reference scopes that can no longer be resurrected.
         for key in scopes_to_delete:
             state = cls._states.pop(key)
-            logger.debug(f"Unregistered ObjectState (cascade): scope={key}")
+            if cls._history_enabled:
+                cls._graveyard[key] = state
+                logger.debug(f"Unregistered ObjectState (cascade): scope={key} (moved to graveyard)")
+            else:
+                logger.debug(f"Unregistered ObjectState (cascade): scope={key}")
             # Fire callbacks for UI binding
             cls._fire_unregister_callbacks(key, state)
 

src/objectstate/parametric_axes.py

@@ -31,7 +31,7 @@ class ChildStep(MyStep, axes={"priority": 1}):
     ChildStep.__axes__["priority"]  # 1 (defined here)
 """
 
-from typing import Dict, Any, Tuple, Optional, Type
+from typing import Dict, Any, Tuple, Optional, Callable
 from types import MappingProxyType
 import weakref
 
@@ -97,6 +97,37 @@ def __repr__(cls) -> str:
         return super().__repr__()
 
 
+# =============================================================================
+# DECORATOR + BASE CLASS (used by tests / ergonomic API)
+# =============================================================================
+
+
+def with_axes(**axes: Any) -> Callable[[type], type]:
+    """Class decorator that attaches axes metadata.
+
+    The decorated class is recreated using :class:`AxesMeta` so it gains:
+    - ``__axes__`` (MappingProxyType)
+    - convenience attributes (``__scope__``, ``__priority__``, etc.)
+    """
+
+    def _decorator(cls: type) -> type:
+        # Recreate class using AxesMeta. Filter out internal descriptors.
+        namespace = {
+            k: v
+            for k, v in cls.__dict__.items()
+            if k not in {"__dict__", "__weakref__"}
+        }
+        return AxesMeta(cls.__name__, cls.__bases__, namespace, axes=axes)
+
+    return _decorator
+
+
+class AxesBase(metaclass=AxesMeta):
+    """Opt-in base class enabling ``class Foo(AxesBase, axes={...})`` syntax."""
+
+    pass
+
+
 # =============================================================================
 # FACTORY FUNCTION - Mimics extended type() signature
 # =============================================================================

tests/conftest.py

@@ -1,4 +1,13 @@
 """Pytest configuration and shared fixtures."""
+import sys
+from pathlib import Path
+
+# Ensure tests exercise the in-repo ObjectState implementation (external/ObjectState/src)
+# rather than any globally installed `objectstate` package.
+_SRC_DIR = Path(__file__).resolve().parents[1] / "src"
+if str(_SRC_DIR) not in sys.path:
+    sys.path.insert(0, str(_SRC_DIR))
+
 import pytest
 from dataclasses import dataclass
 from objectstate import set_base_config_type

tests/test_undo_redo_cascade.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from objectstate.object_state import ObjectState
+from objectstate.object_state_registry import ObjectStateRegistry
+
+
+def _reset_registry_and_history() -> None:
+    """Hard reset for tests.
+
+    ObjectStateRegistry has global process-level state (registry + snapshot DAG).
+    Existing test suite doesn't currently exercise history, so we reset it here.
+    """
+    ObjectStateRegistry._states.clear()
+    ObjectStateRegistry._time_travel_limbo.clear()
+    ObjectStateRegistry._graveyard.clear()
+    ObjectStateRegistry._snapshots.clear()
+    ObjectStateRegistry._timelines.clear()
+    ObjectStateRegistry._current_timeline = "main"
+    ObjectStateRegistry._current_head = None
+    ObjectStateRegistry._in_time_travel = False
+    ObjectStateRegistry._atomic_depth = 0
+    ObjectStateRegistry._atomic_label = None
+
+
+@dataclass
+class Dummy:
+    x: int = 1
+
+
+def test_cascade_unregister_preserves_states_for_time_travel_restore() -> None:
+    _reset_registry_and_history()
+
+    plate_scope = "/tmp/plate"
+    step_scope = f"{plate_scope}::functionstep_4"
+    func_scope = f"{step_scope}::function_0"
+
+    step_state = ObjectState(Dummy(), scope_id=step_scope)
+    func_state = ObjectState(Dummy(), scope_id=func_scope, parent_state=step_state)
+
+    ObjectStateRegistry.register(step_state)
+    ObjectStateRegistry.register(func_state)
+    ObjectStateRegistry.record_snapshot("before delete", scope_id=step_scope)
+    before_id = ObjectStateRegistry.get_branch_history()[-1].id
+
+    # User delete path in OpenHCS uses cascade unregister for step + descendants.
+    ObjectStateRegistry.unregister_scope_and_descendants(step_scope)
+
+    # Undo should resurrect both scopes.
+    ok = ObjectStateRegistry.time_travel_to_snapshot(before_id)
+    assert ok
+    assert ObjectStateRegistry.get_by_scope(step_scope) is not None
+    assert ObjectStateRegistry.get_by_scope(func_scope) is not None