Closes #24

core/dbc_decoder.h

@@ -43,7 +43,8 @@ enum class FrameDecodeStatus {
     UnknownFrame,
     InsufficientPayload,
     SignalErrors,
-    Valid
+    Valid,
+    AmbiguousFrame
 };
 
 /**
@@ -70,7 +71,7 @@ struct DecodedSignalValue {
  */
 struct DecodedFrameValue {
     std::shared_ptr<const DecodeFrame> definition; /**< Owning immutable definition. */
-    FrameKey key;                                  /**< Stable application identifier. */
+    FrameKey key;                                  /**< Matched definition key; received key if unmatched. */
     std::vector<DecodedSignalValue> signals;       /**< Decoded signal values. */
     bool valid = false;                            /**< true if frame was matched. */
     FrameDecodeStatus status = FrameDecodeStatus::UnknownFrame; /**< Inspect signals for individual failures. */
@@ -84,11 +85,11 @@ struct DecodedFrameValue {
 class DbcDecoder {
 public:
     /**
-     * @brief Find frame definition by CAN ID.
+     * @brief Find exact CAN ID first, then unique PGN among explicitly J1939 definitions.
      * @param database Runtime decode database.
      * @param canId Normalized CAN ID.
      * @param isExtended true for extended frame.
-     * @return Owning immutable frame handle or nullptr. Safe across reload.
+     * @return Owning immutable handle, or nullptr for missing/ambiguous matches. Safe across reload.
      */
     std::shared_ptr<const DecodeFrame> FindFrame(const DecodeDatabase &database,
                                                  std::uint32_t canId,
@@ -108,7 +109,8 @@ public:
      * @brief Decode selected signals in selection order using stable keys.
      * An empty selection returns no signals. Multiplex selectors are read internally.
      * Frame status summarizes selected signals; short payload still takes precedence.
-     * Unknown frames return UnknownFrame before checking the selection.
+     * Unknown/ambiguous frames return before checking the selection.
+     * For PGN matches, selection keys must belong to the matched DBC definition.
      * @throws std::invalid_argument for a foreign frame key, unknown signal, or duplicate key.
      */
     DecodedFrameValue Decode(const DecodeDatabase &database,
@@ -116,6 +118,9 @@ public:
                              const std::vector<SignalKey> &selection) const;
 
 private:
+    static PgnLookupResult ResolveFrame(const DecodeDatabase &database,
+                                        std::uint32_t canId, bool isExtended);
+
     DecodedFrameValue DecodeImpl(const DecodeDatabase &database,
                                  const RawCanFrame &frame,
                                  const std::vector<SignalKey> *selection) const;