Closes #15

README.md

@@ -392,7 +392,8 @@ Fields:
 `std::variant<std::int64_t, std::uint64_t>`. For a valid signal, signed definitions
 produce the `int64_t` alternative and unsigned definitions produce the `uint64_t`
 alternative. Raw values remain exact across their full 64-bit ranges. Check
-`valid` before using the value; an invalid result's default value is not decoded data.
+`valid` before using the physical value. Raw data is also available when
+`status == PhysicalConversionFailed`; other invalid results have no decoded numeric data.
 
 Use `std::get` when the numeric type is known, or `std::get_if` to handle both:
 
@@ -428,13 +429,41 @@ Fields:
 - `key`
 - `signals`
 - `valid`
+- `status`
 
 `valid` means a matching frame definition was found. Check each signal's
 `valid` separately: insufficient payload data can leave individual signals
-invalid even when the frame is valid. An unknown frame returns `valid == false`.
+invalid even when the frame is valid. An unknown frame returns `valid == false`,
+a null definition, its requested key, and an empty signal list.
+
+`FrameDecodeStatus` summarizes the result:
+
+| Status | Meaning |
+| --- | --- |
+| `UnknownFrame` | No definition matches both CAN ID and standard/extended type |
+| `InsufficientPayload` | Actual byte count is less than the declared `dlc` |
+| `SignalErrors` | Payload is long enough, but at least one signal failed |
+| `Valid` | Payload is long enough and every signal is valid or inactive |
+
+Short-payload status takes precedence over signal errors; inspect each signal's
+status for the individual cause. `valid` retains its existing meaning of a matched
+definition and does not imply `status == FrameDecodeStatus::Valid`.
+
+Payload policy uses `dlc` as a byte count, including for CAN FD; it is not the
+encoded wire DLC. A shorter payload is never padded: all signals whose bytes are
+available still decode, even if other signals fail. A longer payload is accepted;
+bytes beyond `dlc` are ignored. Signal bit layouts must fit the declared `dlc`, so
+extra bytes cannot rescue an invalid definition. Empty payloads and zero-byte
+frame definitions follow the same rules. Results include every signal in definition
+order, preserving successful values and definition handles on partial failures.
 
 The decoder applies factor and offset; it does not clamp physical values to the
-declared minimum and maximum.
+declared minimum and maximum. Non-finite conversion results (NaN or positive/
+negative infinity), including overflow with finite factor/offset, produce
+`PhysicalConversionFailed`. The exact raw value and non-finite `physicalValue`
+remain available, while signal `valid` is false. Non-finite factor/offset in manually
+constructed definitions follow this same conversion-result check. Physical
+conversion failure of a selector does not prevent raw branch selection.
 
 ### Definition ownership and reload
 
@@ -734,10 +763,12 @@ Each result has `SignalDecodeStatus status`:
 | `Inactive` | Selector is available and chooses another branch |
 | `SelectorUnavailable` | Branch activation is unknown because selector bytes are missing |
 | `InsufficientPayload` | Selected or unconditional signal bytes are missing |
-| `InvalidDefinition` | Invalid bit length or missing/invalid selector in manually built runtime metadata |
+| `InvalidDefinition` | Invalid length, byte order, numeric type, multiplexing role, layout outside declared DLC, or missing/invalid selector in manually built runtime metadata |
+| `PhysicalConversionFailed` | Raw value is available, but the converted physical value is NaN or infinity |
 
-All statuses except `Valid` have `valid == false`; their numeric fields contain
-no decoded data and `GetValueDescription()` returns nullptr. Check `status` to
+All statuses except `Valid` have `valid == false` and `GetValueDescription()`
+returns nullptr. `PhysicalConversionFailed` preserves extracted raw data and the
+non-finite conversion result; other invalid statuses have no decoded numeric data. Check `status` to
 distinguish inactive branches from errors. Consumers constructing runtime metadata
 manually must obey the same non-overlap rules as the parser. Extended and nested
 multiplexing are outside this stage and are explicitly rejected, rather than