docs: scaffold polisher-control foundation

tests/test_contract_constants.py

@@ -0,0 +1,16 @@
+from polisher_control.telemetry_channels import CORE_CHANNELS
+from polisher_control.contracts import MACHINE_ID
+
+
+def test_machine_id_is_fullum_alpha():
+    assert MACHINE_ID == "fullum-alpha"
+
+
+def test_core_telemetry_channels_are_stable():
+    assert CORE_CHANNELS[:4] == [
+        "timestamp_us",
+        "table_angle_deg",
+        "arm_angle_deg",
+        "fz_n",
+    ]
+    assert "force_setpoint_n" in CORE_CHANNELS

tests/test_state_machine.py

@@ -0,0 +1,26 @@
+import pytest
+
+from polisher_control.state_machine import IllegalTransitionError, MachineState, StateMachine
+
+
+def test_manual_mode_path_returns_to_idle():
+    sm = StateMachine()
+    assert sm.trigger("enter_manual") == MachineState.MANUAL
+    assert sm.trigger("exit_manual") == MachineState.IDLE
+
+
+def test_faulted_requires_reset():
+    sm = StateMachine(MachineState.MANUAL)
+    assert sm.trigger("fault") == MachineState.FAULTED
+    with pytest.raises(IllegalTransitionError):
+        sm.trigger("enter_manual")
+    assert sm.trigger("reset") == MachineState.IDLE
+
+
+def test_operator_acknowledge_required_before_running():
+    sm = StateMachine()
+    sm.trigger("load_job")
+    with pytest.raises(IllegalTransitionError):
+        sm.trigger("start")
+    sm.trigger("operator_acknowledge")
+    assert sm.trigger("start") == MachineState.RUNNING