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/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",