Closes #24

README.md

@@ -193,7 +193,7 @@ Notes:
 
 - `signals` is a list of `SignalInfo`
 - `isExtended` is determined during CAN ID normalization
-- `pgn` is derived using simplified J1939 logic when applicable
+- `pgn` is derived for extended frames only with explicit J1939 opt-in (see below)
 
 ---
 
@@ -476,14 +476,16 @@ Fields:
 
 `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`,
-a null definition, its requested key, and an empty signal list.
+invalid even when the frame is valid. An unknown or ambiguous frame returns `valid == false`,
+a null definition, its requested key, and an empty signal list. A successful PGN
+match uses the DBC definition key for the frame and its signals.
 
 `FrameDecodeStatus` summarizes the result:
 
 | Status | Meaning |
 | --- | --- |
-| `UnknownFrame` | No definition matches both CAN ID and standard/extended type |
+| `UnknownFrame` | No exact CAN ID/type match or eligible PGN match |
+| `AmbiguousFrame` | No exact match and multiple J1939 definitions share the PGN |
 | `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 |
@@ -875,17 +877,55 @@ This is important both for correct lookup and for future interoperability with l
 
 ---
 
-## PGN Extraction
+## J1939 Opt-in and PGN Lookup
 
-PGN is derived only when the frame is treated as extended.
+Extended CAN identifiers do not imply J1939. The default parser leaves `hasPgn`
+false and `pgn` zero, and decoding uses exact normalized CAN ID and frame type.
+Enable J1939 interpretation explicitly for a file:
 
-The current logic is simplified J1939 extraction:
+```cpp
+DbcParserOptions options;
+options.enableJ1939 = true;
+const DbcDatabase parsed = DbcParser(options).ParseFile("vehicle.dbc");
+const DecodeDatabase runtime = DbcDecodeBuilder().Build(parsed);
+```
 
-- `pf`
-- `ps`
-- `dp`
+Both parser entry points honor this option. Standard frames remain ordinary CAN.
+For mixed-protocol files, parse with the default options, then set `hasPgn = true`
+and `pgn = ExtractJ1939Pgn(frame.canId)` (from `j1939.h`) only on known J1939
+extended definitions before building the runtime snapshot. The same explicit
+metadata enables J1939 for manually constructed `DecodeFrame` definitions.
+Runtime construction rejects `hasPgn` on standard frames or an inconsistent PGN.
+No DBC attribute automatically enables J1939 interpretation.
 
-This is enough for a practical start but should not be treated as full J1939 validation.
+PGN extraction retains both data-page bits (CAN ID bits 25–24) and PF:
+
+- PDU1 (`PF < 240`): PS is the destination address and is zeroed in the PGN.
+- PDU2 (`PF >= 240`): PS is the group extension and remains part of the PGN.
+- Priority and source address are excluded in both cases. This follows the
+  [Linux J1939 PGN layout](https://docs.kernel.org/networking/j1939.html).
+
+`DecodeDatabase::FindFrame(FrameKey)` stays an exact lookup.
+`FindFrameByPgn(pgn)` returns a `PgnLookupResult` with an owning `definition`
+handle for one eligible definition. No match returns a null handle with
+`ambiguous == false`; multiple definitions return a null handle with
+`ambiguous == true`. Copies and returned handles retain the immutable snapshot.
+
+`DbcDecoder::FindFrame` and both `Decode` overloads first try the exact ID/type.
+Only when that fails for a valid normalized extended ID do they try PGN lookup
+among definitions with `hasPgn == true`. A unique PGN can therefore match a
+changed source address or priority, and for PDU1 a changed destination address.
+A changed PDU2 group extension does not match. Exact matches win even when the
+PGN is ambiguous, including exact matches to ordinary extended CAN definitions.
+Multiple PGN candidates are never resolved by order, source, or payload:
+`FindFrame` returns null and `Decode` returns `AmbiguousFrame` without decoding
+signals or validating the selection. Missing candidates return `UnknownFrame`.
+
+On success, decoded frame/signal keys belong to the matched DBC definition;
+selected-signal decoding also expects those definition keys. Keep the input
+`RawCanFrame` if the received address/ID is needed separately. This feature does
+not implement transport-protocol reassembly, address claiming, or full J1939
+validation.
 
 ---