Closes #16

README.md

@@ -336,8 +336,28 @@ This matters because the same numeric identifier must not be confused between st
 
 Immutable runtime snapshot with a private frame index. Build it with
 `DbcDecodeBuilder::Build(parsed)` or construct it from `std::vector<DecodeFrame>`.
-Construction rejects duplicate frame keys and duplicate signal names within a
-frame with `std::invalid_argument`, including manually supplied metadata.
+Construction validates all definitions before publishing the snapshot and throws
+`std::invalid_argument` for invalid metadata, including manually supplied data:
+
+- Normalized CAN IDs must fit 11 bits for standard frames or 29 bits for extended
+  frames. DBC's bit-31 encoding flag must already be removed.
+- Frame keys must be unique; signal names must be unique within their frame.
+- Signal lengths must be 1–64 bits, with Intel/Motorola layouts entirely inside
+  the declared payload. Bit coordinates use overflow-safe 64-bit arithmetic.
+- Byte order, numeric type, and multiplexing role must be valid enum values.
+- Factor, offset, minimum, and maximum must be finite; minimum must not exceed
+  maximum. Zero and negative factors are allowed.
+- Multiplexing requires one unsigned selector when branches are present, with
+  branch values in its raw range. Signals may overlap only when they are branches
+  selected by different raw values, including mixed byte orders.
+
+`dlc` remains a byte count in the storage range 0–255; construction imposes no
+additional CAN/CAN FD payload limit. A zero-byte frame may contain no signals.
+Both `DbcDecodeBuilder::Build` and the direct constructor apply these rules.
+Construction copies the input, including nested metadata, even for rvalue input.
+Saved mutable aliases into that input cannot modify definitions or invalidate the
+lookup index. Database copies still share the frozen snapshot; a failed
+construction or replacement leaves the previous snapshot and its lookups intact.
 
 - `GetFrames()` returns a borrowed `const std::vector<DecodeFrame>&`.
 - `FindFrame(FrameKey)` returns `std::shared_ptr<const DecodeFrame>`.
@@ -461,9 +481,9 @@ The decoder applies factor and offset; it does not clamp physical values to the
 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.
+remain available, while signal `valid` is false. Non-finite numeric parameters are
+rejected during database construction. Finite parameters can still overflow during
+conversion; conversion failure of a selector does not prevent raw branch selection.
 
 ### Definition ownership and reload
 
@@ -483,8 +503,8 @@ that metadata is no longer needed.
 
 `GetFrames()` is a borrowed view. References, iterators, and raw pointers obtained
 from it or from a handle's `.get()` do not retain ownership. Keep an owning handle
-or an unchanged database copy while using them. Do not retain mutable aliases
-into a vector moved into the database constructor. The raw string pointer from
+or an unchanged database copy while using them. Constructor input is copied and
+may be changed independently afterward. The raw string pointer from
 `GetValueDescription()` follows the same rule: keep the signal definition handle
 alive while using the string.
 
@@ -763,14 +783,14 @@ 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 length, byte order, numeric type, multiplexing role, layout outside declared DLC, or missing/invalid selector in manually built runtime metadata |
+| `InvalidDefinition` | Defensive decoder check failed; invalid definitions are rejected during database construction |
 | `PhysicalConversionFailed` | Raw value is available, but the converted physical value is NaN or infinity |
 
 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
+manually receive the same selector and non-overlap validation as parsed files. Extended and nested
 multiplexing are outside this stage and are explicitly rejected, rather than
 silently decoded as unconditional signals.