sync-state-bridge 1.0.0__py3-none-any.whl

sync_state/__init__.py

@@ -0,0 +1,15 @@
+from .sync_core import StateSync, StateSyncError, ProviderValidationError
+from .qos import QoS, DropPolicy, TypeMetadata
+from .presets import Presets
+from .client_socket import StateSyncSocketClient
+
+__all__ = [
+    "StateSync",
+    "StateSyncError",
+    "ProviderValidationError",
+    "QoS",
+    "DropPolicy",
+    "TypeMetadata",
+    "Presets",
+    "StateSyncSocketClient",
+]

sync_state/client_socket.py

@@ -0,0 +1,75 @@
+import asyncio
+import json
+import struct
+import logging
+from typing import Dict, Any, Callable, Optional
+
+logger = logging.getLogger("sync_state_bridge.client")
+LENGTH_PREFIX = "!I"
+
+
+class StateSyncSocketClient:
+    """Production socket client with automatic exponential backoff reconnection."""
+
+    def __init__(
+        self, 
+        host: str = "127.0.0.1", 
+        port: int = 8765, 
+        on_delta_callback: Optional[Callable[[Dict[str, Any]], None]] = None,
+        max_reconnect_delay: float = 32.0
+    ):
+        self.host = host
+        self.port = port
+        self.on_delta_callback = on_delta_callback
+        self.max_reconnect_delay = max_reconnect_delay
+        self.local_versions: Dict[str, int] = {}
+        self._running = False
+
+    async def connect_and_listen(self):
+        """Persistent event-loop wrapper for network auto-healing."""
+        self._running = True
+        reconnect_delay = 1.0
+
+        while self._running:
+            try:
+                logger.info(f"Connecting to state sync server at {self.host}:{self.port}...")
+                reader, writer = await asyncio.open_connection(self.host, self.port)
+                reconnect_delay = 1.0  # Reset backoff interval on successful handshake
+
+                handshake_payload = json.dumps(self.local_versions).encode("utf-8")
+                header = struct.pack(LENGTH_PREFIX, len(handshake_payload))
+                writer.write(header)
+                writer.write(handshake_payload)
+                await writer.drain()
+
+                while self._running:
+                    header_bytes = await reader.readexactly(4)
+                    (length,) = struct.unpack(LENGTH_PREFIX, header_bytes)
+                    payload_bytes = await reader.readexactly(length)
+                    packet = json.loads(payload_bytes.decode("utf-8"))
+
+                    event = packet.get("event")
+                    data = packet.get("data", {})
+
+                    if event == "manifest":
+                        logger.info(f"Received server manifest. Schema version: {data.get('schema_version')}")
+
+                    elif event == "delta":
+                        type_name = data.get("type")
+                        version = data.get("version", 0)
+                        if type_name:
+                            self.local_versions[type_name] = max(self.local_versions.get(type_name, 0), version)
+
+                        if self.on_delta_callback:
+                            if asyncio.iscoroutinefunction(self.on_delta_callback):
+                                await self.on_delta_callback(data)
+                            else:
+                                self.on_delta_callback(data)
+
+            except (ConnectionRefusedError, asyncio.IncompleteReadError, BrokenPipeError, OSError) as e:
+                logger.warning(f"Connection error ({e}). Reconnecting in {reconnect_delay:.1f}s...")
+                await asyncio.sleep(reconnect_delay)
+                reconnect_delay = min(reconnect_delay * 2.0, self.max_reconnect_delay)
+
+    def stop(self):
+        self._running = False

sync_state/errors.py

@@ -0,0 +1,11 @@
+class StateSyncError(Exception):
+    """Base exception for StateSync operations."""
+
+class ProviderValidationError(StateSyncError):
+    """Raised when a snapshot provider returns invalid or unsafe data."""
+
+class VersionMismatchError(StateSyncError):
+    """Raised when client version is ahead of server (should not happen)."""
+
+class SchemaMismatchError(StateSyncError):
+    """Raised when schema versions differ."""

sync_state/presets.py

@@ -0,0 +1,32 @@
+from .qos import QoS, DropPolicy
+
+
+class Presets:
+    """Pre-configured QoS profiles for common network deployment scenarios."""
+
+    @staticmethod
+    def conservative() -> QoS:
+        """Safe profile for general IP networking; ensures minimal delta loss."""
+        return QoS(
+            drop_policy=DropPolicy.CRITICAL,
+            ideal_cadence_ms=100,
+            ttl_ms=None
+        )
+
+    @staticmethod
+    def low_bandwidth() -> QoS:
+        """Optimized for low-rate interfaces like serial, BLE, or satellite links."""
+        return QoS(
+            drop_policy=DropPolicy.CONFLATABLE,
+            ideal_cadence_ms=250,
+            ttl_ms=500
+        )
+
+    @staticmethod
+    def high_throughput() -> QoS:
+        """High-frequency telemetry stream with aggressive delta drop allowance."""
+        return QoS(
+            drop_policy=DropPolicy.BEST_EFFORT,
+            ideal_cadence_ms=20,
+            ttl_ms=100
+        )

sync_state/qos.py

@@ -0,0 +1,33 @@
+import time
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+
+class DropPolicy(Enum):
+    """Defines how deltas are handled when transport buffers overflow."""
+    CRITICAL = "never_drop"          # Guarded: Queued until delivered, never discarded
+    CONFLATABLE = "keep_latest"      # Conflated: Drops intermediate deltas in favor of newest
+    BEST_EFFORT = "drop_on_overflow" # Discardable: Dropped immediately under queue pressure
+
+
+@dataclass
+class QoS:
+    """Quality of Service metadata for entity streams."""
+    drop_policy: DropPolicy = DropPolicy.CONFLATABLE
+    ideal_cadence_ms: int = 50       # Target refresh interval in ms
+    ttl_ms: Optional[int] = 1000     # Time-To-Live in queue before delta expires
+
+    def is_expired(self, created_at_timestamp: float) -> bool:
+        """Check if a delta has exceeded its TTL in transport queue."""
+        if self.ttl_ms is None or self.drop_policy == DropPolicy.CRITICAL:
+            return False
+        return (time.time() - created_at_timestamp) * 1000.0 > self.ttl_ms
+
+
+@dataclass
+class TypeMetadata:
+    """Registration metadata for snapshot providers."""
+    type_name: str
+    qos: QoS = QoS()
+    max_frame_bytes: int = 1_048_576  # 1MB default chunking threshold

sync_state/sync_core.py

@@ -0,0 +1,266 @@
+import json
+import hashlib
+import asyncio
+import copy
+import time
+from collections import defaultdict, deque
+from typing import Dict, List, Any, Callable, Optional, Set, AsyncIterator
+from .qos import QoS, DropPolicy, TypeMetadata   # if you have these
+
+
+def canonical_hash(entity: Dict[str, Any]) -> str:
+    """Deterministic, canonical SHA-256 hash calculation for dictionaries."""
+    if "_v" in entity:
+        return str(entity["_v"])
+
+    def _default_encoder(o: Any) -> Any:
+        if isinstance(o, (set, tuple)):
+            return list(o)
+        if hasattr(o, "to_dict") and callable(o.to_dict):
+            return o.to_dict()
+        return sorted(list(o.__dict__.items())) if hasattr(o, "__dict__") else str(o)
+
+    try:
+        import orjson
+        encoded = orjson.dumps(entity, option=orjson.OPT_SORT_KEYS, default=_default_encoder)
+    except ImportError:
+        encoded = json.dumps(entity, sort_keys=True, default=_default_encoder).encode('utf-8')
+    return hashlib.sha256(encoded).hexdigest()
+
+class StateSyncError(Exception):
+    """Base exception for StateSync operations."""
+    pass
+
+
+class ProviderValidationError(StateSyncError):
+    """Raised when a snapshot provider returns invalid or unsafe data."""
+    pass
+
+
+class StateSync:
+    def __init__(self, id_key: str = "id", max_history: int = 1000, schema_version: int = 1):
+        self.id_key = id_key
+        self.max_history = max_history
+        self.schema_version = schema_version
+
+        self._lock = asyncio.Lock()
+        self._dirty_types: Set[str] = set()
+        self._snapshot_providers: Dict[str, Callable[[], List[Dict]]] = {}
+
+        self._versions: Dict[str, int] = defaultdict(int)
+        self._change_logs: Dict[str, deque] = defaultdict(lambda: deque(maxlen=max_history))
+        self._current_snapshots: Dict[str, Dict[Any, Dict]] = {}
+        self._type_metadata: Dict[str, TypeMetadata] = {}   # <-- add this
+
+        self._stream_events: List[asyncio.Event] = []
+
+    def register_snapshot_provider(
+        self,
+        type_name: str,
+        provider: Callable[[], List[Dict]],
+        qos: Optional[QoS] = None,
+        max_frame_bytes: int = 1_048_576
+    ):
+        from .qos import QoS, TypeMetadata  # ensure import is available
+        qos_obj = qos or QoS()
+        self._snapshot_providers[type_name] = provider
+        self._type_metadata[type_name] = TypeMetadata(
+            type_name=type_name,
+            qos=qos_obj,
+            max_frame_bytes=max_frame_bytes
+        )
+
+    def mark_dirty(self, type_name: str):
+        self._dirty_types.add(type_name)
+
+    def _canonical_hash(self, entity: Dict) -> str:
+        if "_v" in entity:
+            return str(entity["_v"])
+
+        def _default_encoder(o):
+            if isinstance(o, (set, tuple)):
+                return list(o)
+            return f"__repr__:{type(o).__name__}:{repr(o)}"
+
+        try:
+            import orjson
+            encoded = orjson.dumps(entity, option=orjson.OPT_SORT_KEYS, default=_default_encoder)
+        except ImportError:
+            encoded = json.dumps(entity, sort_keys=True, default=_default_encoder).encode('utf-8')
+        return hashlib.sha256(encoded).hexdigest()
+
+    def _validate_and_sanitize_snapshot(self, raw_entities: Any, type_name: str) -> Dict[Any, Dict]:
+        if not isinstance(raw_entities, (list, tuple)):
+            raise ProviderValidationError(f"Provider for '{type_name}' must return a list or tuple.")
+
+        sanitized = {}
+        for idx, entity in enumerate(raw_entities):
+            if not isinstance(entity, dict):
+                raise ProviderValidationError(f"Entity at index {idx} in '{type_name}' is not a dict.")
+            if self.id_key not in entity:
+                raise ProviderValidationError(f"Entity at index {idx} in '{type_name}' missing key '{self.id_key}'.")
+            eid = entity[self.id_key]
+            if eid is None or not isinstance(eid, (str, int)):
+                raise ProviderValidationError(f"Entity ID at index {idx} in '{type_name}' must be str or int.")
+            if eid in sanitized:
+                raise ProviderValidationError(f"Duplicate entity ID '{eid}' detected in '{type_name}'.")
+            sanitized[eid] = copy.deepcopy(entity)
+        return sanitized
+
+    async def commit(self):
+        dirty_types_to_process = []
+        async with self._lock:
+            if not self._dirty_types:
+                return
+            dirty_types_to_process = list(self._dirty_types)
+            self._dirty_types.clear()
+
+        fetched_snapshots: Dict[str, Dict[Any, Dict]] = {}
+        for type_name in dirty_types_to_process:
+            if type_name in self._snapshot_providers:
+                try:
+                    raw_data = self._snapshot_providers[type_name]()
+                    fetched_snapshots[type_name] = self._validate_and_sanitize_snapshot(raw_data, type_name)
+                except Exception:
+                    async with self._lock:
+                        self._dirty_types.add(type_name)
+                    raise
+
+        async with self._lock:
+            for type_name, new_snapshot in fetched_snapshots.items():
+                old_snapshot = self._current_snapshots.get(type_name, {})
+                old_ids = set(old_snapshot.keys())
+                new_ids = set(new_snapshot.keys())
+
+                self._versions[type_name] += 1
+                current_version = self._versions[type_name]
+
+                added = new_ids - old_ids
+                deleted = old_ids - new_ids
+                common = new_ids & old_ids
+
+                updated = [
+                    eid for eid in common
+                    if self._canonical_hash(old_snapshot[eid]) != self._canonical_hash(new_snapshot[eid])
+                ]
+
+                self._change_logs[type_name].append({
+                    "version": current_version,
+                    "added": list(added),
+                    "updated": updated,
+                    "deleted": list(deleted)
+                })
+                self._current_snapshots[type_name] = new_snapshot
+
+            # Notify all active streams
+            for evt in self._stream_events:
+                evt.set()
+
+    def get_delta(self, type_name: str, client_version: int) -> Dict[str, Any]:
+        snapshot = self._current_snapshots.get(type_name, {})
+        history = self._change_logs.get(type_name)
+        current_version = self._versions.get(type_name, 0)
+
+        if not history or client_version < history[0]["version"] or client_version > current_version:
+            return {
+                "type": type_name,
+                "full": True,
+                "version": current_version,
+                "added": list(snapshot.values()),
+                "updated": [],
+                "deleted": []
+            }
+
+        entity_state: Dict[Any, str] = {}
+        for entry in history:
+            if entry["version"] <= client_version:
+                continue
+            for eid in entry["added"]:
+                entity_state[eid] = "added"
+            for eid in entry["updated"]:
+                if eid not in entity_state:
+                    entity_state[eid] = "updated"
+                elif entity_state[eid] == "added":
+                    continue
+                elif entity_state[eid] == "deleted":
+                    continue
+            for eid in entry["deleted"]:
+                if entity_state.get(eid) == "added":
+                    del entity_state[eid]
+                else:
+                    entity_state[eid] = "deleted"
+
+        added_ids = [eid for eid, state in entity_state.items() if state == "added"]
+        updated_ids = [eid for eid, state in entity_state.items() if state == "updated"]
+        deleted_ids = [eid for eid, state in entity_state.items() if state == "deleted"]
+
+        return {
+            "type": type_name,
+            "full": False,
+            "version": current_version,
+            "added": [snapshot[eid] for eid in added_ids if eid in snapshot],
+            "updated": [snapshot[eid] for eid in updated_ids if eid in snapshot],
+            "deleted": deleted_ids
+        }
+
+    async def stream_deltas(self, client_versions: Dict[str, int], keepalive_interval: int = 15):
+        # Create a per‑stream event on the current loop
+        stream_event = asyncio.Event()
+        self._stream_events.append(stream_event)
+
+        try:
+            local_client_versions = dict(client_versions)
+
+            # Initial sync
+            deltas_to_send = []
+            full_manifest_versions = {}
+
+            async with self._lock:
+                for type_name in self._snapshot_providers:
+                    c_ver = local_client_versions.get(type_name, 0)
+                    delta = self.get_delta(type_name, c_ver)
+                    full_manifest_versions[type_name] = self._versions.get(type_name, 0)
+                    if delta["full"] or delta["added"] or delta["updated"] or delta["deleted"]:
+                        deltas_to_send.append(delta)
+                        local_client_versions[type_name] = delta["version"]
+
+            manifest = {
+                "schema_version": self.schema_version,
+                "versions": full_manifest_versions,
+                "types": list(self._snapshot_providers.keys())
+            }
+
+            yield f"event: manifest\ndata: {json.dumps(manifest)}\n\n"
+
+            for delta in deltas_to_send:
+                yield f"event: delta\ndata: {json.dumps(delta)}\n\n"
+
+            # Reactive loop
+            while True:
+                try:
+                    await asyncio.wait_for(stream_event.wait(), timeout=keepalive_interval)
+                except asyncio.TimeoutError:
+                    # Keepalive
+                    yield f"event: keepalive\ndata: {{}}\n\n"
+                    continue
+
+                # Clear the event so it can be used again
+                stream_event.clear()
+
+                # A commit happened – check for new deltas
+                deltas_to_send = []
+                async with self._lock:
+                    for type_name in self._snapshot_providers:
+                        c_ver = local_client_versions.get(type_name, 0)
+                        delta = self.get_delta(type_name, c_ver)
+                        if delta["full"] or delta["added"] or delta["updated"] or delta["deleted"]:
+                            deltas_to_send.append(delta)
+                            local_client_versions[type_name] = delta["version"]
+
+                for delta in deltas_to_send:
+                    yield f"event: delta\ndata: {json.dumps(delta)}\n\n"
+
+        finally:
+            # Remove this stream's event from the list
+            if stream_event in self._stream_events:
+                self._stream_events.remove(stream_event)

sync_state/transports/__init__.py

@@ -0,0 +1,3 @@
+from .socket_adapter import StateSyncSocketServer
+
+__all__ = ["StateSyncSocketServer"]

sync_state/transports/serial_stub.py

@@ -0,0 +1,24 @@
+from typing import Any, Dict
+
+
+class SerialTransportAdapter:
+    def __init__(self, port: str, baudrate: int = 115200, max_queue_size: int = 25):
+        self.port = port
+        self.baudrate = baudrate
+        self.max_queue_size = max_queue_size
+        raise NotImplementedError("SerialTransportAdapter is currently a stub. Implementation planned for v0.2.0.")
+
+    async def start(self) -> None:
+        raise NotImplementedError
+
+    async def send_delta(self, delta: Dict[str, Any]) -> None:
+        # Lazy import to avoid hard dependency at module load
+        try:
+            import cobs  # noqa: F401
+            import serial  # noqa: F401
+        except ImportError as e:
+            raise RuntimeError(
+                "Serial transport dependencies missing. "
+                "Install via 'pip install sync-state-bridge[serial]'"
+            ) from e
+        raise NotImplementedError

sync_state/transports/socket_adapter.py

@@ -0,0 +1,101 @@
+import asyncio
+import json
+import struct
+import logging
+
+logger = logging.getLogger("sync_state_bridge.socket")
+LENGTH_PREFIX = "!I"
+
+
+class StateSyncSocketServer:
+    def __init__(self, state_sync, max_queue_size: int = 100):
+        self.state_sync = state_sync
+        self.max_queue_size = max_queue_size
+        self.metrics = {
+            "queue_length": 0,
+            "deltas_dropped": 0,
+            "full_snapshots_sent": 0,
+            "client_congested_count": 0
+        }
+
+    async def handle_connection(self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter):
+        outbound_queue: asyncio.Queue[dict] = asyncio.Queue(maxsize=self.max_queue_size)
+        priority_snapshot_queue: asyncio.Queue[dict] = asyncio.Queue(maxsize=10)
+        is_congested = False
+
+        async def _write_worker():
+            nonlocal is_congested
+            while True:
+                if not priority_snapshot_queue.empty():
+                    packet = await priority_snapshot_queue.get()
+                    priority_snapshot_queue.task_done()
+                else:
+                    packet = await outbound_queue.get()
+                    outbound_queue.task_done()
+
+                self.metrics["queue_length"] = outbound_queue.qsize()
+                payload = json.dumps(packet).encode("utf-8")
+                header = struct.pack(LENGTH_PREFIX, len(payload))
+                
+                try:
+                    writer.write(header)
+                    writer.write(payload)
+                    await writer.drain()
+                except (ConnectionResetError, BrokenPipeError, asyncio.CancelledError):
+                    break
+
+        write_task = asyncio.create_task(_write_worker())
+        packet_gen = None
+
+        try:
+            header_bytes = await reader.readexactly(4)
+            (length,) = struct.unpack(LENGTH_PREFIX, header_bytes)
+            client_versions = json.loads((await reader.readexactly(length)).decode("utf-8"))
+
+            packet_gen = self.state_sync.iter_packets(client_versions)
+            async for packet in packet_gen:
+                event_type = packet.get("event")
+                data = packet.get("data", {})
+
+                if event_type == "delta" and data.get("full"):
+                    self.metrics["full_snapshots_sent"] += 1
+
+                try:
+                    outbound_queue.put_nowait(packet)
+                except asyncio.QueueFull:
+                    self.metrics["deltas_dropped"] += 1
+                    if not is_congested:
+                        is_congested = True
+                        self.metrics["client_congested_count"] += 1
+                        logger.warning("Client transport congested. Dropping delta frame.")
+                    
+                    while not outbound_queue.empty():
+                        try:
+                            outbound_queue.get_nowait()
+                            outbound_queue.task_done()
+                        except asyncio.QueueEmpty:
+                            break
+
+                    recovery_packet = {
+                        "event": "delta",
+                        "data": self.state_sync.get_delta(data.get("type", ""), client_version=-1)
+                    }
+                    try:
+                        priority_snapshot_queue.put_nowait(recovery_packet)
+                    except asyncio.QueueFull:
+                        pass
+
+        except (asyncio.IncompleteReadError, ConnectionResetError, BrokenPipeError):
+            pass
+        finally:
+            if packet_gen is not None:
+                await packet_gen.aclose()
+            write_task.cancel()
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+    async def start_tcp(self, host: str = "127.0.0.1", port: int = 8765):
+        return await asyncio.start_server(self.handle_connection, host, port)

sync_state_bridge-1.0.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: sync-state-bridge
+Version: 1.0.0
+Summary: Versioned delta-state synchronization engine for real-time systems, IPC, and embedded applications
+Author-email: Andrew Kingdom <1809762+akingdom@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/akingdom/sync-state-bridge
+Project-URL: Bug-Tracker, https://github.com/akingdom/sync-state-bridge/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Provides-Extra: fast
+Requires-Dist: orjson>=3.8.0; extra == "fast"
+Provides-Extra: serial
+Requires-Dist: pyserial>=3.5; extra == "serial"
+Requires-Dist: cobs>=1.2.0; extra == "serial"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Dynamic: license-file
+
+# sync-state-bridge
+
+A deterministic, race‑safe state synchronisation bridge for real‑time applications, with built‑in QoS, backpressure handling, and network resilience.
+
+- **Versioned, per‑type sync** – each entity type has its own version history.
+- **Segmented deltas** – send only what changed, with a manifest first.
+- **FSM lifecycle** – correct handling of add→update→delete sequences.
+- **Resilient reconnection** – out‑of‑order drop, monotonicity guards, schema mismatch handling.
+- **Quality of Service (QoS)** – define drop policies (CRITICAL, CONFLATABLE, BEST_EFFORT) per entity type.
+- **Backpressure‑aware transports** – bounded queues, priority full‑snapshot injection, congestion metrics.
+- **Reconnecting client** – exponential backoff, version tracking, automatic recovery.
+- **Pure Python + JS** – no binary dependencies.
+
+## Quick Start
+
+Install the server package:
+
+```bash
+pip install sync-state-bridge
+```
+
+For optional features (faster JSON, serial transport):
+
+```bash
+pip install sync-state-bridge[fast,serial]
+```
+
+### Basic Usage
+
+```python
+from sync_state import StateSync, Presets
+
+sync = StateSync()
+
+# Register a snapshot provider with a QoS profile
+sync.register_snapshot_provider(
+    "vehicles",
+    get_vehicles,
+    qos=Presets.low_bandwidth()   # optimised for slow links
+)
+
+# After changes:
+sync.mark_dirty("vehicles")
+await sync.commit()
+
+# Stream deltas over HTTP (SSE)
+from fastapi import FastAPI, StreamingResponse
+app = FastAPI()
+
+@app.get("/stream")
+async def stream(versions: str = "{}"):
+    return StreamingResponse(
+        sync.stream_deltas(json.loads(versions)),
+        media_type="text/event-stream"
+    )
+```
+
+### Socket Server (for low‑level IPC)
+
+```python
+from sync_state.transports import StateSyncSocketServer
+
+server = StateSyncSocketServer(sync)
+await server.start_tcp(host="0.0.0.0", port=8765)
+```
+
+### Reconnecting Client
+
+```python
+from sync_state import StateSyncSocketClient
+
+def handle_delta(delta):
+    print(f"Update: {delta}")
+
+client = StateSyncSocketClient(
+    host="127.0.0.1",
+    port=8765,
+    on_delta_callback=handle_delta
+)
+await client.connect_and_listen()
+```
+
+## Quality of Service (QoS)
+
+Each entity type can have a `QoS` profile:
+
+| Policy        | Behaviour |
+|---------------|-----------|
+| `CRITICAL`    | Never dropped; queued until delivered. |
+| `CONFLATABLE` | Intermediate deltas dropped; only the latest is sent (ideal for high‑frequency telemetry). |
+| `BEST_EFFORT` | Discarded immediately under queue pressure. |
+
+Pre‑configured profiles (`Presets.conservative()`, `Presets.low_bandwidth()`, `Presets.high_throughput()`) are provided.
+
+## Testing
+
+Run the unit tests:
+
+```bash
+pytest tests/
+```
+
+The test suite covers:
+- Deterministic hashing (`canonical_hash`)
+- Commit & delta generation
+- Version‑gap full‑snapshot recovery
+
+## Demos
+
+- **Chat** – real‑time message broadcast with shared history.
+- **Game** – "Find the Clusters" demonstrating turn‑based sync.
+
+Run the demos:
+
+```bash
+cd examples/chat && python server.py
+```
+```bash
+cd examples/game && python server.py
+```
+
+## Protocol
+
+See [`PROTOCOL.md`](./PROTOCOL.md) for the full SSE‑based delta protocol.
+
+## License
+
+MIT

sync_state_bridge-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+sync_state/__init__.py,sha256=nD0VlMOUJKvJDEmBDas9jcbUof8eOaHCuWiE3G-JHCY,377
+sync_state/client_socket.py,sha256=3HZa5CAPDAlahHnwHskOe0A1us3H4c2GvuXcgZAwyhk,3093
+sync_state/errors.py,sha256=SgG4gnP3-E2jlJVr5Z-MJLP6CtmBaEfJUmu0bW4KpMc,417
+sync_state/presets.py,sha256=ezJ46z0lfH5IYVtPhO7RWW5JgTJ6I5A68OVdRl18Vns,937
+sync_state/qos.py,sha256=8XhpjOJUlQh_0vTu7yPSOUDiWgRoNHf6aO_e9QxLxck,1269
+sync_state/sync_core.py,sha256=3DOUxDTmSGcksXYgzxGELk5tzhcc1m3pUymuEAnkJRs,10757
+sync_state/transports/__init__.py,sha256=dxlxX41E6OXJMpVj8x6TbK_UZzFdFEKOz5wjZ10oEKc,87
+sync_state/transports/serial_stub.py,sha256=xb2mLeFDyfyzwJHon3XmwXSpE0fkfi8coaR3T1ScbDY,900
+sync_state/transports/socket_adapter.py,sha256=uChlw_6GoMer17TESYkUdB6xDyoC2hun6rCrqmJZJiE,3928
+sync_state_bridge-1.0.0.dist-info/licenses/LICENSE.md,sha256=3PS64E9B4QMAlNM47CgxOtGQm3mEfvDIOmSde6rJObU,1071
+sync_state_bridge-1.0.0.dist-info/METADATA,sha256=mWqIZ_xOcDVYV0KAfH5FlHxcenuFxirQN89h1OCkOOc,4555
+sync_state_bridge-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sync_state_bridge-1.0.0.dist-info/top_level.txt,sha256=XcYcbcBKi6kZhdY2507ekEjcKuhM1HP6B-XFmjbQEYY,11
+sync_state_bridge-1.0.0.dist-info/RECORD,,

sync_state_bridge-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sync_state_bridge-1.0.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Kingdom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sync_state_bridge-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sync_state