init commit

python_app/orchestration/shm/binary_cursor.py

@@ -0,0 +1,50 @@
+"""Byte-wise cursor utilities for decoding binary ring payloads."""
+
+from __future__ import annotations
+
+import struct
+
+
+class ByteCursor:
+    """Read primitive values from bytes while tracking offset."""
+
+    def __init__(self, payload: bytes) -> None:
+        """Create cursor at start of payload."""
+        self.payload = payload
+        self.offset = 0
+
+    def read_u8(self) -> int:
+        """Read unsigned 8-bit integer."""
+        value = struct.unpack_from("<B", self.payload, self.offset)[0]
+        self.offset += 1
+        return value
+
+    def read_u16(self) -> int:
+        """Read unsigned 16-bit integer."""
+        value = struct.unpack_from("<H", self.payload, self.offset)[0]
+        self.offset += 2
+        return value
+
+    def read_u32(self) -> int:
+        """Read unsigned 32-bit integer."""
+        value = struct.unpack_from("<I", self.payload, self.offset)[0]
+        self.offset += 4
+        return value
+
+    def read_u64(self) -> int:
+        """Read unsigned 64-bit integer."""
+        value = struct.unpack_from("<Q", self.payload, self.offset)[0]
+        self.offset += 8
+        return value
+
+    def read_f32(self) -> float:
+        """Read 32-bit float."""
+        value = struct.unpack_from("<f", self.payload, self.offset)[0]
+        self.offset += 4
+        return float(value)
+
+    def read_bytes(self, size: int) -> bytes:
+        """Read raw byte slice of fixed size."""
+        data = self.payload[self.offset : self.offset + size]
+        self.offset += size
+        return data