load_signal

Once loaded, reference the signal by its signal_id in every analysis,
diagnosis, report, and prognostics tool (the load -> analyze ->
diagnose -> report flow uses signal_id as the single handle).

Batch form: pass a LIST of file paths (e.g. for training sets). The
batch is fail-fast and atomic — all paths and derived ids are
validated up front, and on the first problem ONE error names the
offending entries and nothing is loaded. One declared sampling_rate/
signal_unit applies to all files; per-file metadata wins only when
the parameter is omitted. Custom signal_id is not allowed for a
batch (ids derive from each file's relative path).

signal_id default: the path relative to data/signals/ with separators
replaced by underscores — 'real_train/baseline_1.csv' loads as
'real_train_baseline_1', so same-named files in different folders
never collide silently. Re-loading a path whose id already exists is
an explicit error unless overwrite=True.

Signal unit discipline: ISO 20816-3 severity verdicts require a
DECLARED unit — either via this parameter or a 'signal_unit' field in
the companion _metadata.json (explicit parameter wins). Units are
never guessed from signal amplitude; without a declared unit the ISO
severity block is refused with a structured reason and remedy.

Raw binary files (.bin/.raw/.dat): a headerless raw waveform loads
only with a declared decode contract — sample_format AND
sampling_rate are REQUIRED, either as explicit parameters here or as
fields of the companion <stem>_metadata.json next to the file
(explicit parameter wins). The other raw parameters carry documented
defaults, applied by the repository after that merge: byte_order
'little', n_channels 1, channel_index 0, header_offset 0, no
scale_factor. Integer sample formats (int16/int32) decode to raw ADC
counts — declare scale_factor to convert counts into the declared
physical unit (there is no implicit normalization). In a batch the
raw parameters broadcast to ALL files, exactly like sampling_rate.
Declaring raw parameters for a self-describing format (.csv, .npy,
...) is refused as a contradiction. With n_channels > 1 each load
extracts ONE channel and the DERIVED id gains a _ch<channel_index>
suffix; an explicit signal_id is used verbatim — no suffix applies.

Args:
    ctx: MCP context. Unused — see this module's docstring on logging.
    filepath: Filename relative to data/signals/ or absolute path —
        or a list of such paths for an atomic batch load.
    signal_id: Custom ID (single-file loads only; default derives
        from the relative path).
    sampling_rate: Sampling rate in Hz (overrides metadata file).
        Required for raw binary files (here or in the companion).
    signal_unit: Declared signal unit — 'g' or 'm/s2' (acceleration),
        'mm/s' or 'm/s' (velocity). Overrides the metadata file.
    overwrite: Replace existing entries on signal_id collision
        instead of raising.
    sample_format: Raw files only — declared sample dtype ('float32',
        'float64', 'int16', 'int32'). REQUIRED for .bin/.raw/.dat
        (here or in the companion metadata).
    byte_order: Raw files only — declared endianness ('little' or
        'big'); documented default 'little'.
    n_channels: Raw files only — interleaved channel count in the
        file; documented default 1.
    channel_index: Raw files only — 0-based channel to extract;
        documented default 0.
    header_offset: Raw files only — bytes to skip before the first
        sample; documented default 0.
    scale_factor: Raw files only — optional multiplier applied after
        decoding (e.g. ADC counts -> physical unit); default: no
        scaling.

Asset ledger: a file whose companion declares a "measurement" object
(asset_id, measurement_point_id, acquired_at, ...) is also RECORDED in
the local append-only asset ledger after the load, and its health
snapshot is derived and appended; the returned measurement block
carries the outcome (ledger_status, snapshot_status, changed keys of a
corrected declaration, comparability against the declared point,
missing snapshot blocks with their remedy). A ledger problem never
fails the load: it is reported as ledger_status 'not_recorded' with
the reason, and re-loading the file is a safe retry. Re-loading the
same file with the same declaration appends nothing
('already_recorded'); a corrected companion supersedes the previous
declaration ('superseded') and the history keeps both.

Returns:
    StoredSignalInfo for a single load; a list of StoredSignalInfo
    (input order) for a batch. Raw loads record the effective decode
    parameters under raw_format; loads with an asset identity carry
    the ledger outcome in the measurement block (see StoredSignalInfo).

Raises:
    ValueError: If signal_unit is invalid, the signal data cannot be
        loaded, a signal_id collides without overwrite=True, a batch
        contains any invalid entry (nothing is loaded), a raw binary
        file is missing a required declaration (ONE message names
        everything missing plus both remedies), or raw parameters
        are declared for a self-describing format.