feat: add spindle direction selection contract

host/polisher_control/contracts.py

@@ -1,6 +1,50 @@
+from enum import StrEnum
+
+
 CONTROLLER_SCHEMA_VERSION = "controller-job.v1"
 RUN_LOG_SCHEMA_VERSION = "run-log.v1"
 MANUAL_SESSION_SCHEMA_VERSION = "manual-session-log.v1"
 MACHINE_CAPABILITIES_SCHEMA_VERSION = "machine-capabilities.v1"
 MACHINE_ID = "fullum-alpha"
 CONTROLLER_VERSION_PREFIX = "polisher-control/"
+
+
+class SpindleDirection(StrEnum):
+    """Toolhead spindle rotation direction using stable protocol/schema values.
+
+    Physical convention: clockwise/counter-clockwise are as viewed from above the
+    toolhead looking down toward the mirror/tool contact. ODrive sign mapping is
+    a commissioning item and must be configured so these UI/protocol values match
+    the observed tool rotation.
+    """
+
+    CLOCKWISE = "cw"
+    COUNTER_CLOCKWISE = "ccw"
+
+    @classmethod
+    def allowed_values(cls) -> list[str]:
+        return [direction.value for direction in cls]
+
+
+_SPINDLE_DIRECTION_ALIASES = {
+    "cw": SpindleDirection.CLOCKWISE,
+    "clockwise": SpindleDirection.CLOCKWISE,
+    "c.w.": SpindleDirection.CLOCKWISE,
+    "ccw": SpindleDirection.COUNTER_CLOCKWISE,
+    "counterclockwise": SpindleDirection.COUNTER_CLOCKWISE,
+    "counter-clockwise": SpindleDirection.COUNTER_CLOCKWISE,
+    "counter_clockwise": SpindleDirection.COUNTER_CLOCKWISE,
+    "anticlockwise": SpindleDirection.COUNTER_CLOCKWISE,
+}
+
+
+def normalize_spindle_direction(value: str | SpindleDirection) -> SpindleDirection:
+    """Normalize UI/protocol aliases to a SpindleDirection enum."""
+    if isinstance(value, SpindleDirection):
+        return value
+    key = value.strip().lower()
+    try:
+        return _SPINDLE_DIRECTION_ALIASES[key]
+    except KeyError as exc:
+        allowed = ", ".join(SpindleDirection.allowed_values())
+        raise ValueError(f"Unsupported spindle direction {value!r}; expected one of: {allowed}") from exc

host/polisher_control/telemetry_channels.py

@@ -28,6 +28,8 @@ RECOMMENDED_CHANNELS = [
     "arm_angle_linearized_deg",
     "table_rpm_setpoint",
     "spindle_rpm_setpoint",
+    "spindle_direction_setpoint",
+    "spindle_direction_actual",
     "force_actuator_cmd",
     "estop_active",
     "interlock_state",