Quaternion library audit: deduplicate utils/ vs math/, add NodeProtocol typing, API stability tests

[Copilot]

13 quaternion functions had independent duplicate implementations in both spinstep/utils/ and spinstep/math/. This PR makes math/ the single source of truth and converts utils/ to a backward-compatible re-export layer. It also addresses all 5 immediate Pre-Phase 1 refactoring items from the multi-observer implementation plan.

Duplication resolution

• utils/quaternion_utils.py: replaced 230 LOC of duplicate implementations with re-exports from spinstep.math.{core,geometry,conversions,analysis}
• utils/quaternion_math.py: replaced with re-export from spinstep.math.analysis
• utils/__init__.py: marked as deprecated, points users to spinstep.math

# Both paths now resolve to the same function object
from spinstep.math import quaternion_multiply
from spinstep.utils import quaternion_multiply as qm_compat
assert quaternion_multiply is qm_compat  # True

NodeProtocol typing

• Added NodeProtocol (typing.Protocol) in spinstep.math.analysis with orientation: np.ndarray
• Replaced object type hints in get_relative_spin() and get_unique_relative_spins() with NodeProtocol
• Removed # type: ignore[union-attr] comments — structural typing validates .orientation access
• Exported NodeProtocol from spinstep.math

Node.add_child()

• Added Node.add_child(child) -> Node convenience method for ergonomic tree building

CI workflow

• Updated .github/workflows/ci.yml to trigger on feature/* branches (push and PR)

CHANGELOG

• Added comprehensive 0.5.0a0 release notes covering control subsystem, math library, traversal reorganization, deprecations, and new typing

API stability tests (test_api.py)

• 97 parametrized tests covering __all__ exports for all 4 subpackages
• Verifies utils re-exports are identity-equal to math implementations
• Validates PEP 561 py.typed marker and PEP 440 version format
• Tests NodeProtocol structural typing (real Node + custom class)
• Tests Node.add_child() method
• Asserts all 21 modules are importable

Packaging (pyproject.toml)

• Version → 0.5.0a0
• Added Typing :: Typed classifier, Changelog/Documentation URLs, py.typed in package-data
• Added mypy overrides for scipy.*, sklearn.*, healpy.*, cupy.*

Lint fixes

• Fixed 6 pre-existing ruff violations in test files (unused imports, == True, unused variables)

Test results: 228 passed, 5 skipped (CUDA/healpy unavailable)

[VoxleOne]

1. Implementation Plan: Multi-Observer / Any-Node-as-Observer Upgrade
   Concept
   Currently, SpinStep's observer-centered spherical model places a single, implicit observer at the origin. All OrientationState instances describe position relative to this fixed observer. The proposed upgrade extends this so that any node can be an observer, enabling:
   • Relative state computation between any two nodes
   • Scene graphs where each node has its own local frame
   • Multi-agent control where each agent sees the world from its own perspective
   • Rich spatial queries like "what does Node B see from its position?"
   Phase 1: Foundation — Node ↔ State Unification (MVP)
   Goal: Bridge the gap between Node (traversal) and OrientationState (control), creating a unified spatial entity.
   Key Tasks:

   1. Create SpatialNode (or extend Node) — Add distance: float, angular_velocity, radial_velocity, timestamp fields to nodes. This unifies the traversal node with control state.
   2. Define NodeProtocol — A typing.Protocol with .orientation, .distance, .name attributes. Replace object type hints in get_relative_spin() and similar functions with this Protocol.
   3. Create RelativeState function — compute_relative_state(observer: SpatialNode, target: SpatialNode) -> OrientationState that computes the target's state as seen from the observer's frame.
   4. Add Node.as_state() and OrientationState.as_node() — Bidirectional conversion methods.
      Dependencies: None (builds on existing code) Risks: API break for Node constructor if fields are added. Mitigate with optional parameters and backward-compatible defaults. Estimated Complexity: Medium (~400-600 LOC, ~20-30 new tests)
      Phase 2: Frame Transforms — Observer-Relative Computation
      Goal: Enable any node to act as a local reference frame with proper coordinate transforms.
      Key Tasks:
   5. Create ReferenceFrame class — Encapsulates an observer position (quaternion + distance from world origin) and provides to_local(state) -> OrientationState and to_world(state) -> OrientationState transforms.
   6. Implement rebase_state(state, from_frame, to_frame) — Transform a state from one observer's frame to another's. This is the core of multi-observer support.
   7. Add frame parameter to OrientationController.update() — Controllers can now operate in any frame, not just the implicit world frame.
   8. Extend OrientationTrajectory to support frame-relative waypoints — Waypoints can be specified relative to a moving observer.
      Dependencies: Phase 1 (SpatialNode, RelativeState) Risks: Quaternion composition errors in frame transforms are subtle. Requires extensive numerical testing with known ground-truth scenarios. Estimated Complexity: High (~600-800 LOC, ~40-50 new tests)
      Phase 3: Scene Graph — Multi-Node Topology
      Goal: Replace tree-only traversal with a graph-aware spatial scene that supports any-node observation.
      Key Tasks:
   9. Create SceneGraph class — A container of SpatialNode instances with adjacency relationships (directed or undirected edges). Support both tree and general graph topologies.
   10. Implement SceneGraph.observe_from(node) — Returns all other nodes' states as seen from the given node's frame. This is the "any node as observer" capability.
   11. Create graph traversal iterators — BreadthFirstIterator, GraphQuaternionIterator that work on SceneGraph instead of trees.
   12. Add spatial indexing — Replace sklearn BallTree with an integrated spatial index (scipy KDTree or custom) that supports efficient nearest-neighbor queries in the spherical domain.
       Dependencies: Phase 1 + Phase 2 (SpatialNode, ReferenceFrame) Risks: Graph cycles, disconnected components, and large graphs (1M+ nodes) need careful handling. Spatial indexing performance is critical. Estimated Complexity: High (~800-1200 LOC, ~50-70 new tests)
       Phase 4: Multi-Agent Control — Production
       Goal: Enable multiple controlled agents, each with their own observer frame, operating in a shared scene.
       Key Tasks:
   13. Create Agent class — Wraps a SpatialNode + OrientationController + optional TrajectoryController. Each agent has its own reference frame.
   14. Implement AgentManager — Coordinates multiple agents: parallel state updates, inter-agent proximity queries, collision avoidance hooks.
   15. Add event system — on_state_change, on_proximity_threshold, on_trajectory_complete callbacks for reactive behavior.
   16. Add serialization — JSON/MessagePack serialization for SceneGraph, Agent, and OrientationTrajectory for persistence and network transport.
       Dependencies: All prior phases Risks: Multi-agent coordination introduces concurrency concerns. Event ordering must be deterministic. Estimated Complexity: Very High (~1000-1500 LOC, ~80-100 new tests)

2. Recommendations
   3.1 Immediate Refactoring (Pre-Phase 1)

   1. Resolve utils/ ↔ math/ duplication. Make utils/ re-export from math/ modules instead of maintaining independent implementations. Add deprecation warnings to direct utils imports. This is the single highest-priority cleanup.
   2. Add NodeProtocol typing. Replace object type hints in get_relative_spin() and get_unique_relative_spins() with a Protocol defining .orientation: np.ndarray.
   3. Add mypy overrides for scipy/sklearn/healpy/cupy. Add [[tool.mypy.overrides]] sections to pyproject.toml — this eliminates ~620 of 650 mypy errors immediately.
   4. Update CI workflow triggers. Add feature/* to the CI branch triggers so the feature branch gets automated testing.
   5. Update CHANGELOG.md for the 0.4.0a0 work (control subsystem, math library refactor).
      3.2 Library/Framework Suggestions
      Need
      Current
      Recommended
      Spatial queries
      sklearn.BallTree (~200MB)
      scipy.spatial.KDTree (already a dependency) — drop scikit-learn
      Serialization
      None
      dataclasses_json or manual to_dict()/from_dict() methods
      Event system
      None
      Simple callback lists (no external dependency needed)
      Graph data structure
      None
      networkx (for prototyping) or custom adjacency-list (for performance)
      GPU acceleration
      cupy (optional)
      Keep as-is; consider jax for future differentiable control
      3.3 Tooling Improvements
   6. Add scipy-stubs to dev dependencies — Eliminates 500+ mypy import-untyped errors.
   7. Add pytest-cov to CI — Track coverage metrics; current coverage is likely 80%+ but unmeasured.
   8. Add pre-commit hooks — Enforce ruff, black, and mypy checks before commits.
   9. Consider sphinx for docs — The existing docstrings are rich enough for auto-generated API reference.
   10. Add benchmarking to CI — The benchmark/ directory exists but isn't integrated with CI.
       3.4 Target Environment Guidance
       For production use targeting 1M+ vertices at 60 FPS:
       • The current numpy-based math is suitable for ~10K nodes at interactive rates
       • For 100K+ nodes: vectorize batch_quaternion_angle and state updates (already partially done)
       • For 1M+ nodes: GPU path via cupy is essential; consider sparse graph representations
       • For real-time (16ms budget): pre-allocate arrays, avoid Python-level iteration, profile DiscreteOrientationSet.query_within_angle
       3.5 Use Case Alignment
       Use Case
       Current Support
       After Phase 4
       Single robot orientation control
       ✅ Full
       ✅ Full
       3D scene tree traversal
       ✅ Full
       ✅ Full
       Multi-robot coordination
       ❌
       ✅ Full
       Scientific visualization (globe)
       Partial (HEALPix)
       ✅ Full
       CAD / scene graph editing
       ❌
       ✅ With SceneGraph
       Real-time simulation (60 FPS)
       ⚠️ Small scenes only
       ✅ With GPU path
       Autonomous navigation mesh
       ❌
       ✅ With graph traversal

Summary
SpinStep feature/0.5.0a0 is a well-engineered alpha with strong fundamentals: clean domain model, production-quality controllers (P/PID with anti-windup), comprehensive math library, and good test coverage (131/136 tests passing). The primary architectural limitation — a single, implicit observer — is the exact target of the proposed upgrade.
The 4-phase plan (Node-State Unification → Frame Transforms → Scene Graph → Multi-Agent) is designed to extend the centered-observer metaphor to any node incrementally, preserving backward compatibility at each phase. The most urgent pre-work is resolving the utils/↔math/ duplication and improving type-checking hygiene.

[Copilot]

1. Implementation Plan: Multi-Observer / Any-Node-as-Observer Upgrade
   Concept
   Currently, SpinStep's observer-centered spherical model places a single, implicit observer at the origin. All Orient...

Addressed the immediate Pre-Phase 1 refactoring items:

1. utils/ ↔ math/ duplication — already resolved in 087d8b9 (13 functions → re-exports)
2. NodeProtocol typing — added typing.Protocol in spinstep.math.analysis, replacing object hints in get_relative_spin() and get_unique_relative_spins(). Removed # type: ignore comments. (15c9523)
3. mypy overrides — already in place from 087d8b9
4. CI workflow triggers — added feature/* to push/PR branch triggers in ci.yml (15c9523)
5. CHANGELOG — added comprehensive 0.5.0a0 release notes covering control subsystem, math library, traversal reorg, and deprecations (15c9523, c8c6033)

Also added Node.add_child() convenience method and 97 API stability tests. 228 tests pass, 5 skipped (CUDA/healpy).