"""
micromate/idf_file.py — placeholder for the Thor IDF binary codec.

Thor's ``.IDFH`` (histogram) and ``.IDFW`` (waveform) event files are an
Instantel proprietary binary format that has not yet been reverse-
engineered.  Today seismo-relay treats them as opaque blobs:
``WaveformStore.save_imported_idf`` stores the bytes verbatim and reads
all device-authoritative metadata from the paired ``.IDFW.txt`` /
``.IDFH.txt`` ASCII sidecar (parsed by ``idf_ascii_report.py``).

When we crack the binary codec — same reverse-engineering playbook we
used to byte-perfect-parse Series III BW files (see
``docs/instantel_protocol_reference.md`` and ``minimateplus/event_file_io.py``)
— this module will grow:

  - ``read_idf_file(path) -> IdfEvent``
        Parse a ``.IDFW``/``.IDFH`` binary and return a fully populated
        ``IdfEvent`` whose waveform-sample arrays come from the binary
        (the .txt sidecar's tabular sample block being a best-effort
        check).  Lets us ingest Thor events even when the operator
        hasn't enabled the .txt exporter — closing the
        ``had_report=False`` gap that the thor-watcher forwarder
        currently tolerates as a known limitation.

  - ``write_idf_file(path, event)`` (eventually)
        Round-trip event reconstruction, used for verifying the codec
        against captured device files the way ``write_blastware_file``
        verifies the Series III codec.

  - Helpers for decoding the binary's per-channel sample arrays into
    physical units, the per-event flash buffer's monitor-log records,
    etc.

The reverse-engineering path: pair every ``.IDFW`` binary in
``thor-watcher/example-data/`` with its sibling ``.IDFW.txt``, treating
the txt's "Waveform Data Channels" block as ground-truth, and align
the binary's per-channel int16-or-similar arrays against it.  Header
fields (sample rate, channel count, record time, timestamps) sit before
the sample block — same approach as the BW codec where ASCII strings
inside the binary (``Project:``, ``Client:``, etc.) anchored field
discovery.
"""

from __future__ import annotations

from pathlib import Path
from typing import Union

from .models import IdfEvent


def read_idf_file(path: Union[str, Path]) -> "IdfEvent":
    """Parse a Thor ``.IDFW``/``.IDFH`` binary into an ``IdfEvent``.

    Not yet implemented.  When implemented, this will be the canonical
    entry point for reading Thor binaries — the ASCII sidecar parser
    becomes an optional fast-path metadata supplement rather than the
    sole source of device-authoritative data.
    """
    raise NotImplementedError(
        "IDF binary codec not yet implemented; the .IDFW/.IDFH binary format "
        "is undecoded.  Use parse_idf_report() on the paired .txt sidecar "
        "for device-authoritative metadata."
    )