Closes #24

core/decode_database.h

@@ -68,7 +68,7 @@ struct DecodeFrame {
     bool isExtended = false;           /**< true for extended frame. */
     std::uint8_t dlc = 0U;             /**< Payload length. */
     std::uint32_t pgn = 0U;            /**< PGN if available. */
-    bool hasPgn = false;               /**< true if PGN is valid. */
+    bool hasPgn = false;               /**< Explicit J1939 opt-in; pgn must match canId. */
     std::string transmitter;           /**< Transmitter ECU. */
     std::string comment;               /**< Frame comment. */
     std::vector<DecodeSignal> signals; /**< Signal definitions. */
@@ -80,6 +80,12 @@ struct DecodeFrame {
     }
 };
 
+/** A PGN lookup rejects multiple definitions rather than choosing by order. */
+struct PgnLookupResult {
+    std::shared_ptr<const DecodeFrame> definition;
+    bool ambiguous = false;
+};
+
 /**
  * @brief Immutable runtime snapshot. Copies share storage; reload replaces a snapshot.
  * Owning lookup handles and decoded results keep old definitions alive.
@@ -98,6 +104,8 @@ public:
     const std::vector<DecodeFrame> &GetFrames() const;
     /** Owning handles retain the entire snapshot across reload or destruction. */
     std::shared_ptr<const DecodeFrame> FindFrame(const FrameKey &key) const;
+    /** Only explicitly marked hasPgn frames participate; ambiguous results have no definition. */
+    PgnLookupResult FindFrameByPgn(std::uint32_t pgn) const;
     std::shared_ptr<const DecodeSignal> FindSignal(const SignalKey &key) const;
 
 private:
@@ -105,6 +113,8 @@ private:
         std::vector<DecodeFrame> frames;
         std::unordered_map<FrameKey, std::size_t, FrameKeyHasher> frameIndexByKey;
 
+        std::unordered_map<std::uint32_t, std::vector<std::size_t>> frameIndicesByPgn;
+
         explicit Storage(const std::vector<DecodeFrame> &definitions);
     };