Revised error codes and functional PlaybackEngine

All internal and public errors have been revised (GPT 5.6 Sol) to return
more detail without horrendously long error classes, this has reduced
the number of error types but each now carries a reason and a code for
differentiation if needed

PlaybackEngine has been implemented and is functional, core mode changes
what signal descriptors are returned to avoid duplicates, the playback
engine currently discards the derived signals that would be recorded in
the DLPak and derived signals are reprocessed live

Future will require the behavior listed above to be selectable so one of
two options are possible:
A - Derived signals are reprocessed live by the relevant derive units
(current behavior
B - Derived signals are played back directly from the PlaybackEngine,
this requires turning off the routing to the live derive units to avoid
duplicate values

This will also require the option to perform offline processing with
derive units to be able to create derived signals after the fact, this
will likely incur a new 'offline' mode in the core to gate things
correctly, this will likely be useful for heavier processing that cannot
be done live, filters that require a lookahead, or more precise derived
signals using interpolated signals for higher acurracy which also brings
the ability to offline process on a fixed timebase instead of following
either input signal to the derived signal

src/dynalab_core/__init__.py

@@ -19,11 +19,8 @@ from dynalab_core.config import CoreConfig
 from dynalab_core.constants import CORE_VERSION
 from dynalab_core.derive import DeriveRegistry
 from dynalab_core.dlpak import DLPak
-from dynalab_core.errors import (
-    CoreModeIncorrectError,
-    CoreModeSwitchImpossibleError,
-    CoreStateMismatchError,
-)
+from dynalab_core.errors import CoreError
+from dynalab_core.playback import PlaybackEngine
 from dynalab_core.protocols.endpoint import ConnectorRegistry
 from dynalab_core.protocols.common import VersionDescriptor
 from dynalab_core.protocols.json.server import JsonServer
@@ -61,6 +58,8 @@ class Core:
         )
         self._input_worker_thread.start()
 
+        self._playback_engine = PlaybackEngine(self._data_input_queue)
+
         self._derive_registry = DeriveRegistry(
             self._data_input_queue, self._get_live_value_descriptor
         )
@@ -80,8 +79,10 @@ class Core:
                     "expected_state": "initd",
                 },
             )
-            raise CoreStateMismatchError(
-                f'Unable to start DynaLab Core, expected state to be "initd", found {self._state}'
+            raise CoreError(
+                f"Cannot start DynaLab Core while it is {self._state!r}; "
+                "a Core instance can only be started once",
+                code="invalid_state",
             )
 
         log.info(
@@ -114,6 +115,7 @@ class Core:
             extra={"event": "core.stopping", "core_state": self._state},
         )
         json_server_stopped = self._json_server.stop()
+        self._playback_engine.stop()
         connector_registry_stopped = self._connector_registry.stop()
         derive_registry_stopped = self._derive_registry.stop()
         self._stop_event.set()
@@ -157,16 +159,54 @@ class Core:
         return stopped
 
     def set_mode(self, mode: CoreMode) -> None:
+        if mode not in ("realtime", "playback"):
+            raise CoreError(
+                f"Unknown core mode {mode!r}; expected 'realtime' or 'playback'",
+                code="invalid_mode",
+            )
         if self._recording.is_set():
-            raise CoreModeSwitchImpossibleError
+            raise CoreError(
+                "Cannot change core mode while a recording is active",
+                code="recording_active",
+            )
 
         self._mode.value = mode
         with self._live_values_lock:
             self._live_values = {}
 
+    def get_mode(self) -> CoreMode:
+        return self._mode.value
+
+    def load_playback_engine(self, input: Path | None = None) -> None:
+        if self._mode.value != "playback":
+            raise CoreError(
+                "Cannot load playback unless the core is in 'playback' mode",
+                code="invalid_mode",
+            )
+        if input is None:
+            if self._processing_buffer is None:
+                raise CoreError(
+                    "Cannot load playback because no recording is available",
+                    code="no_playback_data",
+                )
+            loaded_data = self._processing_buffer
+        else:
+            loaded_data = DLPak().read(input)
+        self._playback_engine.set_data(loaded_data)
+
+    # def unload_playback_engine
+
     def start_recording(self) -> None:
         if self._mode.value != "realtime":
-            raise CoreModeIncorrectError
+            raise CoreError(
+                "Cannot start recording unless the core is in 'realtime' mode",
+                code="incorrect_mode",
+            )
+        if self._recording.is_set():
+            raise CoreError(
+                "Cannot start recording because a recording is already active",
+                code="recording_active",
+            )
         self._recording_buffer.clear()
         self._recording_timestamp = datetime.now(timezone.utc)
         self._recording.set()
@@ -180,7 +220,15 @@ class Core:
 
     def stop_recording(self) -> None:
         if self._mode.value != "realtime":
-            raise CoreModeIncorrectError
+            raise CoreError(
+                "Cannot stop recording unless the core is in 'realtime' mode",
+                code="incorrect_mode",
+            )
+        if not self._recording.is_set():
+            raise CoreError(
+                "Cannot stop recording because no recording is active",
+                code="not_recording",
+            )
         self._recording.clear()
         time.sleep(1)
         self._recording_buffer.normalize()
@@ -213,17 +261,29 @@ class Core:
             },
         )
 
+    def get_recording_state(self) -> bool:
+        return self._recording.is_set()
+
     def get_signal_descriptor(self, signal_id: UUID) -> SignalDescriptor | None:
-        signal = self._connector_registry.get_signal_descriptor(signal_id)
+        signal: SignalDescriptor | None = None
+        if self._mode.value == "realtime":
+            signal = self._connector_registry.get_signal_descriptor(signal_id)
+        elif self._mode.value == "playback":
+            signal = self._playback_engine.get_signal_descriptor(signal_id)
+
         if signal is None:
             signal = self._derive_registry.get_signal_descriptor(signal_id)
 
         return signal
 
     def get_all_signal_descriptors(self) -> list[SignalDescriptor]:
-        connector_signals = self._connector_registry.get_all_signal_descriptors()
+        root_signals: list[SignalDescriptor] = []
+        if self._mode.value == "realtime":
+            root_signals = self._connector_registry.get_all_signal_descriptors()
+        elif self._mode.value == "playback":
+            root_signals = self._playback_engine.get_all_signal_descriptors()
         derive_signals = self._derive_registry.get_all_signal_descriptors()
-        return connector_signals + derive_signals
+        return root_signals + derive_signals
 
     def get_live_value(self, signal_id: UUID) -> float | None:
         with self._live_values_lock:
@@ -252,8 +312,40 @@ class Core:
         self._derive_registry.unregister(unit_id)
 
     def write(self, dir: str | Path, filename: str) -> None:
-        if self._processing_buffer is not None:
-            self._processing_buffer.write(dir, filename)
+        if self._processing_buffer is None:
+            raise CoreError(
+                "Cannot write recording because no recording is available",
+                code="no_recording",
+            )
+        self._processing_buffer.write(dir, filename)
+
+    def play(self) -> None:
+        if self._mode.value != "playback":
+            raise CoreError(
+                "Cannot play unless the core is in 'playback' mode",
+                code="invalid_mode",
+            )
+        self._playback_engine.play()
+
+    def pause(self) -> None:
+        if self._mode.value != "playback":
+            raise CoreError(
+                "Cannot pause unless the core is in 'playback' mode",
+                code="invalid_mode",
+            )
+        self._playback_engine.pause()
+
+    def seek(self, timestamp_ns: int) -> None:
+        if self._mode.value != "playback":
+            raise CoreError(
+                "Cannot seek unless the core is in 'playback' mode",
+                code="invalid_mode",
+            )
+        self._playback_engine.seek(timestamp_ns)
+
+    def get_playback_state(self) -> bool:
+        # TODO: internalize playback state to PlaybackEngine
+        return self._playback_engine._playing.is_set()
 
     def _get_live_value_descriptor(self, signal_id: UUID) -> ValueDescriptor | None:
         with self._live_values_lock:

src/dynalab_core/buffer.py

@@ -2,6 +2,7 @@
 # Copyright (C) 2026 Association Exergie <association.exergie@gmail.com>
 # SPDX-License-Identifier: GPL-3.0-or-later
 
+from bisect import bisect_right
 from collections import defaultdict
 import csv
 import io
@@ -46,6 +47,62 @@ class ValueBuffer:
         with self._lock:
             self._samples.sort(key=lambda sample: sample[0])
 
+    def import_csv(self, input: str) -> None:
+        reader = csv.reader(io.StringIO(input, newline=""))
+
+        header = next(reader, None)
+
+        if header is None:
+            raise ValueError("CSV input is empty")
+
+        if not header or header[0] != "timestamp_ns":
+            raise ValueError("The first CSV column must be 'timestamp_ns'")
+
+        try:
+            signal_ids = [UUID(column) for column in header[1:]]
+        except ValueError as error:
+            raise ValueError(
+                "CSV contains an invalid signal UUID in its header"
+            ) from error
+
+        if len(signal_ids) != len(set(signal_ids)):
+            raise ValueError("CSV contains duplicate signal UUID columns")
+
+        imported_samples: list[tuple[int, UUID, float]] = []
+
+        for line_number, row in enumerate(reader, start=2):
+            if not row or all(cell == "" for cell in row):
+                continue
+            if len(row) != len(header):
+                raise ValueError(
+                    f"Line {line_number} has {len(row)} columns; expected {len(header)}"
+                )
+
+            try:
+                timestamp_ns = int(row[0])
+            except ValueError as error:
+                raise ValueError(
+                    f"Line {line_number} has an invalid timestamp: {row[0]!r}"
+                ) from error
+
+            for signal_id, cell in zip(signal_ids, row[1:]):
+                if cell == "":
+                    continue
+
+                try:
+                    value = float(cell)
+                except ValueError as error:
+                    raise ValueError(
+                        f"Line {line_number} has an invalid value: {cell!r}"
+                    ) from error
+
+                imported_samples.append((timestamp_ns, signal_id, value))
+
+        imported_samples.sort(key=lambda sample: sample[0])
+
+        with self._lock:
+            self._samples = imported_samples
+
     def export_csv(self) -> str:
         with self._lock:
             samples = list(self._samples)
@@ -81,3 +138,12 @@ class ValueBuffer:
             )
 
         return output.getvalue()
+
+    def get_samples_from(self, timestamp: int) -> list[tuple[int, UUID, float]]:
+        with self._lock:
+            index = bisect_right(
+                self._samples,
+                timestamp,
+                key=lambda sample: sample[0],
+            )
+            return self._samples[index:].copy()

src/dynalab_core/derive.py

@@ -12,12 +12,7 @@ import threading
 import types
 from uuid import UUID, uuid4
 
-from dynalab_core.errors import (
-    DeriveRegistryAlreadyRegisteredError,
-    DeriveUnitArgsMismatchError,
-    DeriveUnitInvalidSignatureError,
-    DeriveUnitMultipleFunctionsFoundError,
-)
+from dynalab_core.errors import DeriveError
 from dynalab_core.protocols.packets.data import ValueDescriptor
 from dynalab_core.protocols.packets.handshake import SignalDescriptor
 
@@ -64,13 +59,35 @@ class DeriveUnit:
                     self._parser_state = ParserState.SIGNAL_DONE
                     continue
                 else:
-                    raise DeriveUnitInvalidSignatureError
+                    raise DeriveError(
+                        f"Parameter {name!r} must be annotated as SignalDescriptor",
+                        code="invalid_signature",
+                    )
 
             if self._parser_state == ParserState.SIGNAL_DONE:
-                raise DeriveUnitInvalidSignatureError
+                raise DeriveError(
+                    f"Parameter {name!r} appears after the output signal parameter",
+                    code="invalid_signature",
+                )
 
         if sig.return_annotation is not ValueDescriptor:
-            raise DeriveUnitInvalidSignatureError
+            raise DeriveError(
+                "The derive function must return ValueDescriptor",
+                code="invalid_signature",
+            )
+
+        if self._parser_state != ParserState.SIGNAL_DONE:
+            raise DeriveError(
+                "The derive function must end with one SignalDescriptor parameter",
+                code="invalid_signature",
+            )
+
+        if self._num_input_args != len(self._input_signals):
+            raise DeriveError(
+                f"Derive function accepts {self._num_input_args} input value(s), but "
+                f"{len(self._input_signals)} input signal(s) were configured",
+                code="input_signal_mismatch",
+            )
 
         self._worker_thread: Thread = Thread(
             target=self._worker_function, name=f"{self._id}_worker_thread", daemon=True
@@ -142,7 +159,11 @@ class DeriveUnit:
     def process_offline(self, input_args: list[ValueDescriptor]) -> ValueDescriptor:
         if len(input_args) == self._num_input_args:
             return self._process_function(*input_args, self._return_signal)
-        raise DeriveUnitArgsMismatchError
+        raise DeriveError(
+            f"Derive unit expected {self._num_input_args} input value(s), "
+            f"received {len(input_args)}",
+            code="argument_mismatch",
+        )
 
     def get_input_signals(self) -> list[SignalDescriptor]:
         return self._input_signals
@@ -214,18 +235,30 @@ class DeriveRegistry:
                             "reason": "duplicate_uuid",
                         },
                     )
-                    raise DeriveRegistryAlreadyRegisteredError
+                    raise DeriveError(
+                        f"Derive unit {unit_uuid} is already registered",
+                        code="already_registered",
+                    )
         unit_id = unit_uuid or uuid4()
 
         namespace = {}
-        exec(function, namespace)
+        try:
+            exec(function, namespace)
+        except Exception as error:
+            raise DeriveError(
+                f"Could not load derive function: {error}",
+                code="invalid_source",
+            ) from error
 
         functions = [
             obj for obj in namespace.values() if isinstance(obj, types.FunctionType)
         ]
 
         if len(functions) != 1:
-            raise DeriveUnitMultipleFunctionsFoundError
+            raise DeriveError(
+                f"Derive source must define exactly one function; found {len(functions)}",
+                code="invalid_source",
+            )
 
         unit = DeriveUnit(
             unit_id, functions[0], input_signals, output_signal, self._core_input_queue

src/dynalab_core/dlpak.py

@@ -5,13 +5,13 @@
 from datetime import datetime, timezone
 import logging
 from pathlib import Path
-from typing import Literal
+from typing import Literal, Self
 from zipfile import ZIP_DEFLATED, ZipFile
 
 from pydantic import BaseModel, Field
 
 from dynalab_core.buffer import ValueBuffer
-from dynalab_core.errors import DLPakNoDataError
+from dynalab_core.errors import DLPakError
 from dynalab_core.protocols.packets.handshake import SignalDescriptor
 
 log = logging.getLogger(__name__)
@@ -38,7 +38,10 @@ class DLPak:
         self, timestamp: datetime, all_signals: list[SignalDescriptor]
     ) -> None:
         if self._data is None:
-            raise DLPakNoDataError
+            raise DLPakError(
+                "Cannot create a DLPak manifest before setting its data",
+                code="no_data",
+            )
 
         data_signal_ids = self._data.get_signal_ids()
 
@@ -52,9 +55,62 @@ class DLPak:
             timestamp=timestamp, signals=manifest_signals, comments=""
         )
 
+    def read(self, file: str | Path) -> Self:
+        input_path = Path(file)
+
+        try:
+            with ZipFile(input_path, mode="r") as archive:
+                manifest = RecordManifest.model_validate_json(
+                    archive.read("manifest.json")
+                )
+                data = ValueBuffer()
+                data.import_csv(archive.read("data.csv").decode("utf-8"))
+        except Exception as error:
+            log.exception(
+                "Failed to read DLPak archive from %s",
+                input_path.name,
+                extra={
+                    "event": "dlpak.read_failed",
+                    "input_filename": input_path.name,
+                    "exception_type": type(error).__name__,
+                },
+            )
+            raise DLPakError(
+                f"Could not read DLPak archive {input_path}: {error}",
+                code="read_failed",
+            ) from error
+
+        self._dir = input_path.parent
+        self._filename = input_path.name
+        self._data = data
+        self._manifest = manifest
+
+        log.info(
+            "Read DLPak archive from %s",
+            input_path.name,
+            extra={
+                "event": "dlpak.read",
+                "input_filename": input_path.name,
+                "sample_count": len(data),
+                "signal_count": len(manifest.signals),
+            },
+        )
+        return self
+
     def write(self, dir: str | Path, filename: str) -> None:
         output_dir = Path(dir)
 
+        if self._data is None:
+            raise DLPakError(
+                "Cannot write a DLPak archive before setting its data",
+                code="no_data",
+            )
+        if self._manifest is None:
+            raise DLPakError(
+                "Cannot write a DLPak archive before creating its manifest",
+                code="no_manifest",
+            )
+
         if output_dir.is_file():
             output_dir = output_dir.parent
 
@@ -81,7 +137,10 @@ class DLPak:
                     "exception_type": type(error).__name__,
                 },
             )
-            raise
+            raise DLPakError(
+                f"Could not write DLPak archive {output_path}: {error}",
+                code="write_failed",
+            ) from error
 
         log.info(
             "Wrote DLPak archive to %s",

src/dynalab_core/errors.py

@@ -2,53 +2,53 @@
 # Copyright (C) 2026 Association Exergie <association.exergie@gmail.com>
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-# Core error declarations
-class CoreError(Exception):
-    """DynaLab Core error."""
+"""Public exceptions raised by DynaLab Core.
+
+Catch a subsystem exception when recovery depends on where an operation failed,
+or catch :class:`DynaLabError` to handle every expected library error. The
+``code`` attribute is stable and intended for programmatic decisions; the
+exception message is written for people.
+"""
 
 
-class CoreModeIncorrectError(CoreError):
-    """DynaLab Core mode error."""
+class DynaLabError(Exception):
+    """Base class for expected errors raised by DynaLab Core."""
+
+    def __init__(self, message: str, *, code: str) -> None:
+        self.code = code
+        super().__init__(message)
 
 
-class CoreModeSwitchImpossibleError(CoreError):
-    """DynaLab Core mode error."""
+class CoreError(DynaLabError):
+    """The core cannot perform the requested lifecycle or mode operation."""
 
 
-class CoreStateMismatchError(CoreError):
-    """DynaLab Core state error."""
+class DLPakError(DynaLabError):
+    """A DLPak archive cannot be prepared, read, or written."""
 
 
-# DLPak error declarations
-class DLPakError(Exception):
-    """DLPak error."""
+class DeriveError(DynaLabError):
+    """A derive unit cannot be created or used as requested."""
 
 
-class DLPakNoDataError(DLPakError):
-    """DLPak no data error."""
+class PlaybackError(DynaLabError):
+    """The playback engine cannot perform the requested operation."""
 
 
-# DeriveUnit error declarations
-class DeriveUnitError(Exception):
-    """DeriveUnit error."""
+class ConnectorError(DynaLabError):
+    """A connector endpoint or registry operation failed."""
 
 
-class DeriveUnitInvalidSignatureError(DeriveUnitError):
-    """DeriveUnit invalid processing function signature error."""
+class JsonServerError(DynaLabError):
+    """The JSON protocol server cannot perform the requested operation."""
 
 
-class DeriveUnitArgsMismatchError(DeriveUnitError):
-    """DeriveUnit incorrect arguments provided error."""
-
-
-class DeriveUnitMultipleFunctionsFoundError(DeriveUnitError):
-    """DynaLab Core multiple functions found while trying to create derive unit."""
-
-
-# DeriveRegistry error declarations
-class DeriveRegistryError(Exception):
-    """Generic ConnectorRegistry Error"""
-
-
-class DeriveRegistryAlreadyRegisteredError(DeriveRegistryError):
-    """ConnectorRegistry endpoint already registered"""
+__all__ = [
+    "ConnectorError",
+    "CoreError",
+    "DLPakError",
+    "DeriveError",
+    "DynaLabError",
+    "JsonServerError",
+    "PlaybackError",
+]

src/dynalab_core/playback.py

@@ -3,6 +3,155 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 
+import logging
+from queue import Queue
+import threading
+import time
+from uuid import UUID
+
+from dynalab_core.dlpak import DLPak
+from dynalab_core.errors import PlaybackError
+from dynalab_core.protocols.packets import ProtocolMessage
+from dynalab_core.protocols.packets.data import ValueDescriptor
+from dynalab_core.protocols.packets.handshake import SignalDescriptor
+
+log = logging.getLogger(__name__)
+
+
 class PlaybackEngine:
-    def __init__(self) -> None:
-        pass
+    def __init__(self, data_queue: Queue[ProtocolMessage]) -> None:
+        self._data: DLPak | None = None
+        self._data_queue: Queue[ProtocolMessage] = data_queue
+        self._playing: threading.Event = threading.Event()
+        self._internal_timestamp: int = 0
+        self._start_timestamp: int = 0
+        self._stop_event: threading.Event = threading.Event()
+        self._stopped_event: threading.Event = threading.Event()
+        self._ignored_signals: set[UUID] = set()
+        self._worker_thread: threading.Thread = threading.Thread(
+            target=self._playback_worker, name="playback_worker_thread", daemon=True
+        )
+        self._worker_thread.start()
+
+    def stop(self) -> None:
+        self._stop_event.set()
+        self._stopped_event.wait(5.0)
+
+    def play(self) -> None:
+        if self._stop_event.is_set():
+            raise PlaybackError(
+                "Cannot start playback after the playback engine has stopped",
+                code="stopped",
+            )
+        if self._data is None:
+            raise PlaybackError(
+                "Cannot start playback before loading data",
+                code="no_data",
+            )
+        self._playing.set()
+
+    def pause(self) -> None:
+        self._playing.clear()
+
+    def seek(self, timestamp_ns: int) -> None:
+        if timestamp_ns < 0:
+            raise PlaybackError(
+                "Playback timestamp cannot be negative",
+                code="invalid_timestamp",
+            )
+        self._internal_timestamp = timestamp_ns
+
+    def get_signal_descriptor(self, uuid: UUID) -> SignalDescriptor | None:
+        if self._data is not None and self._data._manifest is not None:
+            for signal in self._data._manifest.signals:
+                if signal.id == uuid:
+                    return signal
+        return None
+
+    def get_all_signal_descriptors(self) -> list[SignalDescriptor]:
+        if self._data is not None and self._data._manifest is not None:
+            return [
+                signal
+                for signal in self._data._manifest.signals
+                if signal.origin != "derived"
+            ]
+
+        return list[SignalDescriptor]()
+
+    def set_data(self, data: DLPak) -> None:
+        if self._playing.is_set():
+            raise PlaybackError(
+                "Cannot replace playback data while playback is active",
+                code="already_playing",
+            )
+        if data._data is None or data._manifest is None:
+            raise PlaybackError(
+                "Cannot load an incomplete DLPak archive for playback",
+                code="incomplete_data",
+            )
+        self._data = data
+        self._ignored_signals = {
+            signal.id
+            for signal in self._data._manifest.signals
+            if signal.origin == "derived"
+        }
+
+    def _update_internal_timestamp(self) -> None:
+        self._internal_timestamp = time.monotonic_ns() - self._start_timestamp
+
+    def _playback_worker(self) -> None:
+        try:
+            self._run_playback()
+        except Exception as error:
+            log.exception(
+                "Playback worker failed",
+                extra={
+                    "event": "playback.worker_failed",
+                    "thread_name": threading.current_thread().name,
+                    "exception_type": type(error).__name__,
+                },
+            )
+        finally:
+            self._playing.clear()
+            self._stopped_event.set()
+
+    def _run_playback(self) -> None:
+        while not self._stop_event.is_set():
+            if not self._playing.is_set():
+                time.sleep(0.05)
+                continue
+
+            if self._data is None:
+                self._playing.clear()
+                continue
+            samples = self._data._data.get_samples_from(self._internal_timestamp)
+
+            if not samples:
+                self._playing.clear()
+                continue
+
+            self._start_timestamp = time.monotonic_ns() - self._internal_timestamp
+            for timestamp, uuid, value in samples:
+                if uuid in self._ignored_signals:
+                    continue
+                while timestamp > self._internal_timestamp:
+                    if not self._playing.is_set() or self._stop_event.is_set():
+                        break
+                    self._update_internal_timestamp()
+                    remaining = timestamp - self._internal_timestamp
+
+                    if remaining > 1_000_000:
+                        time.sleep((remaining - 500_000) / 1_000_000_000)
+
+                if not self._playing.is_set() or self._stop_event.is_set():
+                    break
+                self._data_queue.put(
+                    ValueDescriptor(
+                        signal_id=uuid,
+                        value=value,
+                        timestamp=timestamp + self._start_timestamp,
+                    )
+                )
+
+            self._playing.clear()
+            self._internal_timestamp = 0

src/dynalab_core/protocols/endpoint.py

@@ -11,10 +11,7 @@ from uuid import UUID
 
 from dynalab_core.types import CoreModeState
 from dynalab_core.constants import HELLO_PACKET, INTERNAL_CONNECTOR_HELLO
-from dynalab_core.protocols.errors import (
-    ConnectorEndpointQueueFullError,
-    ConnectorRegistryAlreadyRegisteredError,
-)
+from dynalab_core.errors import ConnectorError
 from dynalab_core.protocols.packets import ProtocolMessage
 from dynalab_core.protocols.packets.data import ValueBatch, ValueDescriptor
 from dynalab_core.protocols.packets.handshake import (
@@ -135,11 +132,14 @@ class ConnectorEndpoint:
     def put_ingress_packet(self, packet: ProtocolMessage) -> None:
         try:
             self._packet_ingress_queue.put_nowait(packet)
-        except Full:
+        except Full as error:
             self._log_queue_full(
                 "ingress", self._packet_ingress_queue, action="rejected"
             )
-            raise ConnectorEndpointQueueFullError
+            raise ConnectorError(
+                f"Connector {self.uuid()} ingress queue is full",
+                code="queue_full",
+            ) from error
 
     def get_egress_packet(self, timeout: float | None) -> ProtocolMessage:
         return self._packet_egress_queue.get(block=True, timeout=timeout)
@@ -156,9 +156,12 @@ class ConnectorEndpoint:
     def _put_egress_packet(self, packet: ProtocolMessage) -> None:
         try:
             self._packet_egress_queue.put_nowait(packet)
-        except Full:
+        except Full as error:
             self._log_queue_full("egress", self._packet_egress_queue, action="rejected")
-            raise ConnectorEndpointQueueFullError
+            raise ConnectorError(
+                f"Connector {self.uuid()} egress queue is full",
+                code="queue_full",
+            ) from error
 
     def _log_queue_full(
         self,
@@ -517,7 +520,10 @@ class ConnectorRegistry:
                         "reason": "duplicate_uuid",
                     },
                 )
-                raise ConnectorRegistryAlreadyRegisteredError
+                raise ConnectorError(
+                    f"Connector {hello.connector_uuid} is already registered",
+                    code="already_registered",
+                )
 
             endpoint = ConnectorEndpoint(
                 hello,

src/dynalab_core/protocols/errors.py

@@ -2,21 +2,12 @@
 # Copyright (C) 2026 Association Exergie <association.exergie@gmail.com>
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-# ConnectorEndpoint error declarations
-class ConnectorEndpointError(Exception):
-    """Generic ConnectorEndpoint Error"""
+"""Protocol exception compatibility import.
 
+``ConnectorError`` is defined with the rest of the public exception hierarchy
+in :mod:`dynalab_core.errors`.
+"""
 
-class ConnectorEndpointQueueFullError(ConnectorEndpointError):
-    """ConnectorEndpoing queue is full"""
+from dynalab_core.errors import ConnectorError
 
-
-# ConnectorRegistry error declarations
-
-
-class ConnectorRegistryError(Exception):
-    """Generic ConnectorRegistry Error"""
-
-
-class ConnectorRegistryAlreadyRegisteredError(ConnectorRegistryError):
-    """ConnectorRegistry endpoint already registered"""
+__all__ = ["ConnectorError"]

src/dynalab_core/protocols/json/errors.py

@@ -2,25 +2,12 @@
 # Copyright (C) 2026 Association Exergie <association.exergie@gmail.com>
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-# JsonServer error declarations
-class JsonServerError(Exception):
-    """Generic JsonServer Error"""
+"""JSON server exception compatibility import.
 
+``JsonServerError`` is defined with the rest of the public exception hierarchy
+in :mod:`dynalab_core.errors`.
+"""
 
-class JsonServerTimeoutError(JsonServerError):
-    """JsonServer timed out"""
+from dynalab_core.errors import JsonServerError
 
-
-class JsonServerStartupError(JsonServerError):
-    """JsonServer crashed on startup"""
-
-    def __init__(self, error: Exception) -> None:
-        self.error = error
-        super().__init__(f"JSON server failed to start: {error}")
-
-
-class JsonServerValueError(JsonServerError):
-    """JsonServer incorrect value detected"""
-
-    def __init__(self, message: str) -> None:
-        super().__init__(str)
+__all__ = ["JsonServerError"]

src/dynalab_core/protocols/json/server.py

@@ -15,11 +15,7 @@ from uuid import uuid4
 from dynalab_core.config import CoreConfig
 from dynalab_core.constants import HELLO_PACKET
 from dynalab_core.protocols.endpoint import ConnectorEndpoint, ConnectorRegistry
-from dynalab_core.protocols.errors import ConnectorRegistryAlreadyRegisteredError
-from dynalab_core.protocols.json.errors import (
-    JsonServerStartupError,
-    JsonServerTimeoutError,
-)
+from dynalab_core.errors import ConnectorError, JsonServerError
 from dynalab_core.protocols.json.wire import read_message, write_message
 from dynalab_core.protocols.packets.handshake import ConnectorHello, HandshakeAccepted
 
@@ -70,10 +66,16 @@ class JsonServer:
                     "timeout_s": self._timeout,
                 },
             )
-            raise JsonServerTimeoutError
+            raise JsonServerError(
+                f"JSON server did not start within {self._timeout:.1f} seconds",
+                code="start_timeout",
+            )
 
         if self._startup_error is not None:
-            raise JsonServerStartupError(self._startup_error)
+            raise JsonServerError(
+                f"JSON server failed to start: {self._startup_error}",
+                code="startup_failed",
+            ) from self._startup_error
 
         bound_addresses = [
             str(sock.getsockname()) for sock in (self._server.sockets or [])
@@ -404,17 +406,30 @@ class JsonServer:
                     **context,
                 },
             )
-        except ConnectorRegistryAlreadyRegisteredError:
-            reason = "duplicate_connector"
-            log.debug(
-                "Connection %s rejected because its connector is already registered",
-                connection_id,
-                extra={
-                    "event": "json_connection.rejected",
-                    "reason": reason,
-                    **context,
-                },
-            )
+        except ConnectorError as error:
+            if error.code == "already_registered":
+                reason = "duplicate_connector"
+                log.debug(
+                    "Connection %s rejected because its connector is already registered",
+                    connection_id,
+                    extra={
+                        "event": "json_connection.rejected",
+                        "reason": reason,
+                        **context,
+                    },
+                )
+            else:
+                reason = "connector_error"
+                log.exception(
+                    "Connection %s failed in the connector subsystem",
+                    connection_id,
+                    extra={
+                        "event": "json_connection.failed",
+                        "reason": reason,
+                        "error_code": error.code,
+                        **context,
+                    },
+                )
         except Exception as error:
             reason = "handler_failed"
             log.exception(