Closes #29

README.md

@@ -370,9 +370,9 @@ index or publishing the snapshot, and throws
 - 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.
+- Multiplexing requires unsigned selectors when branches are present, with
+  branch ranges inside the parent's raw range. Signals may overlap only when
+  their ancestor conditions prove mutual exclusion, 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.
@@ -609,7 +609,7 @@ The current parser supports the following DBC elements:
 - `CM_ BO_`
 - `CM_ SG_`
 - `VAL_` signal value descriptions
-- basic `M` / `mN` multiplexing
+- basic and extended multiplexing (`M`, `mN`, `mNM`, `SG_MUL_VAL_`)
 
 ### Structured diagnostics
 
@@ -639,7 +639,7 @@ if (!result.HasErrors()) {
 | `Error` / `InvalidValueDescription` | Invalid `VAL_` syntax, duplicate value, or unresolved reference |
 | `Error` / `InvalidMultiplexing` | Selector, branch range, or signal overlap validation failed |
 | `Warning` / `UnsupportedStatement` | Unregistered statement skipped; decoding or metadata may be incomplete |
-| `Error` / `UnsupportedStatement` | Extended multiplexing (`SG_MUL_VAL_`) rejected |
+| `Error` / `InvalidMultiplexing` | Invalid `SG_MUL_VAL_` syntax, references, ranges, or cycles |
 
 Parsing stops at the first error and returns an empty database, together with
 any preceding warnings and the error. Deferred comment, `VAL_`, and multiplexing errors
@@ -809,8 +809,8 @@ numbers, NaN, infinity, conversion overflow, and conversion underflow (including
 subnormal values) are
 rejected. Minimum must not exceed maximum. Zero and negative factors are allowed.
 
-Basic multiplexing markers `M` and `mN` are supported as described below.
-Overlapping signals are rejected unless their branch values differ.
+Basic and extended multiplexing markers are supported as described below.
+Overlapping signals are rejected unless their selector conditions prove mutual exclusion.
 Duplicate frame keys and signal names within a frame are rejected.
 
 Invalid signal definitions stop parsing with `path:line: description`, including
@@ -818,7 +818,7 @@ when the signal exceeds the declared payload length.
 
 ---
 
-## Basic multiplexing
+## Multiplexing
 
 ```dbc
 BO_ 256 Status: 3 ECU
@@ -829,24 +829,49 @@ BO_ 256 Status: 3 ECU
 ```
 
 `SignalInfo` and `DecodeSignal` contain `multiplexing`: a `MultiplexRole`
-(`Unconditional`, `Selector`, or `Branch`) and an exact `uint64_t` branch `value`.
-Each frame may have one unsigned selector (`M`); a branch (`mN`) references that
-selector implicitly. The selector may appear after its branches. `N` must contain
-only decimal digits, fit `uint64_t`, and fit the selector's bit width. Leading
-zeros are accepted. A selector without branches is allowed. Signed selectors,
-missing selectors, multiple selectors, nested/combined markers, and extended
-`SG_MUL_VAL_` statements are rejected with the originating `path:line`.
-The dispatcher registers the unsupported statement handler through `TypeFactory`.
+(`Unconditional`, `Selector`, `Branch`, or `BranchSelector`), an exact `uint64_t`
+marker `value`, and optional parent `selector` name with inclusive `ranges`.
+`M` declares an unsigned selector; `mN` declares a branch and `mNM` declares a
+branch that is itself a selector. Without explicit ranges, `mN`/`mNM` use the
+unique unconditional `M` selector and the marker's raw value. If several root
+selectors exist, branches require explicit references.
 
-Signal bits may overlap only between branches with different selector values.
-This validation uses Intel or Motorola bit traversal, including mixed byte orders.
-It also rejects overlapping unconditional signals. Metadata survives the runtime
+Extended conditions use `SG_MUL_VAL_ <message-id> <signal> <selector> <low>-<high>, ...;`:
+
+```dbc
+BO_ 1 Nested: 3 ECU
+ SG_ Root M : 0|8@1+ (1,0) [0|255] "" ECU
+ SG_ Child m1M : 8|8@1+ (1,0) [0|255] "" ECU
+ SG_ Value m0 : 16|8@1+ (1,0) [0|255] "" ECU
+SG_MUL_VAL_ 1 Child Root 1-2, 4-4;
+SG_MUL_VAL_ 1 Value Child 3-5;
+```
+
+Here `Value` is active when `Root` is 1, 2, or 4 **and** `Child` is 3 through 5.
+Explicit ranges override the marker value. Repeated statements for the same
+signal/selector merge their range alternatives. Each signal has at most one
+parent selector; conflicting parent references are rejected. Multiple independent
+root selectors are supported. Statements and selectors may precede or follow
+their targets. Decimal values retain the full `uint64_t` range and must fit the
+parent's bit width. Ranges are stored without expanding individual values.
+Malformed ranges, unresolved references, signed selectors, ambiguous implicit
+selectors, and dependency cycles produce `InvalidMultiplexing` diagnostics.
+Statement errors retain the `SG_MUL_VAL_` source line; graph and overlap errors
+identify the affected signal declaration.
+
+Signal bits may overlap only when the complete ancestor conditions prove the
+signals mutually exclusive: at least one shared selector has disjoint ranges.
+This includes nested siblings using the same payload bits and independent
+selectors, whose branches may be active simultaneously. Validation uses Intel or
+Motorola bit traversal, including mixed byte orders. Metadata survives runtime
 and tree builders; the optional Qt adapter does not add multiplexing roles yet.
 
-The shared decoder extracts the selector before processing branches, compares its
-**raw unsigned value**, and leaves result order equal to definition order. Factor,
-offset, and `VAL_` descriptions do not influence branch selection. Unconditional
-signals continue to decode. An unmapped selector value leaves all branches inactive.
+The decoder checks ancestors from root to leaf using **raw unsigned values**.
+An inactive ancestor leaves descendants inactive even if their selector bytes
+are absent. Missing bytes on an otherwise active selector path produce
+`SelectorUnavailable`. Selective decoding reads required ancestors internally;
+result order remains selection or definition order. Factor, offset, and `VAL_`
+descriptions do not influence branch selection.
 
 Each result has `SignalDecodeStatus status`:
 
@@ -863,9 +888,7 @@ 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 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.
+manually receive the same selector graph and non-overlap validation as parsed files.
 
 ---
 
@@ -1154,7 +1177,7 @@ lines:
 - `SG_` → `DbcSignalHandler`
 - `CM_` → `DbcCommentHandler`
 - `VAL_` → `DbcValueDescriptionHandler`
-- `SG_MUL_VAL_` → `DbcUnsupportedMultiplexingHandler`
+- `SG_MUL_VAL_` → `DbcMultiplexingHandler`
 - `VERSION`, `NS_`, `BS_`, `BU_` → `DbcHeaderHandler` (also accepts attached colons)
 
 Grammar implementations live in `core/dbc_statement_handler.cpp`; their interface,
@@ -1250,7 +1273,7 @@ This is still a minimal implementation.
 
 Not supported yet:
 
-- extended and nested multiplexing (`SG_MUL_VAL_`, `mNM`)
+- multiple parent selectors for one signal
 - named `VAL_TABLE_` tables and environment-variable value descriptions
 - attribute relation forms (`BA_REL_`, `BA_DEF_REL_`)
 - `SIG_VALTYPE_` floating-point signal types
@@ -1307,7 +1330,7 @@ Recommended additions:
 
 Recommended additions:
 
-- basic multiplexing (implemented)
+- basic, extended, and nested multiplexing (implemented)
 - attribute parsing (implemented for definitions, defaults and values)
 - richer J1939 support
 - CSV export of decoded traces