wireforge 0.1.0__py3-none-any.whl

wireforge/_data/runtime/include/wireforge/dispatcher.hpp

@@ -0,0 +1,339 @@
+/**
+ * @file dispatcher.hpp
+ * @brief Routes received frames or payloads to message handlers.
+ */
+#ifndef WIREFORGE_DISPATCHER_HPP
+#define WIREFORGE_DISPATCHER_HPP
+
+#include "wireforge/array_access.hpp"
+#include "wireforge/byte_io.hpp"
+#include "wireforge/delegate.hpp"
+#include "wireforge/frame_layout.hpp"
+#include "wireforge/lock.hpp"
+#include "wireforge/span.hpp"
+#include "wireforge/status.hpp"
+
+#include <algorithm>
+#include <array>
+#include <atomic>
+#include <cstddef>
+#include <cstdint>
+#include <iterator>
+
+namespace wireforge {
+
+/**
+ * @brief A received message before decoding.
+ *
+ * Both spans point into the caller's buffer (for a Link: its receive frame buffer) and are valid
+ * only while the handler runs.
+ */
+struct RawMessage {
+    Span<const std::uint8_t> payload; ///< Bytes between header and trailer.
+    Span<const std::uint8_t> frame;   ///< The whole frame: header, payload and trailer.
+};
+
+/// @brief Handler of one message type; receives the raw message and returns the decode result.
+using MessageHandler = Delegate<Status(const RawMessage&)>;
+
+/// @brief Handler for message ids without a registered handler; receives the id and the raw
+/// message.
+using FallbackHandler = Delegate<Status(std::uint64_t, const RawMessage&)>;
+
+/// @brief Where the message id and the payload are inside a frame.
+struct HeaderLayout {
+    std::size_t header_size;  ///< Header bytes; the payload starts right after them.
+    std::size_t trailer_size; ///< Trailer bytes at the end of the frame.
+    FieldLocation message_id; ///< Message id field inside the header.
+    Endian endian;            ///< Byte order of the message id field.
+};
+
+/// @brief Statistics of a dispatcher; readable from any thread.
+struct DispatchCounters {
+    RelaxedCounter dispatched;  ///< Payloads passed to a registered handler.
+    RelaxedCounter fallback;    ///< Payloads passed to the fallback handler.
+    RelaxedCounter unknown_ids; ///< Payloads dropped because no handler matched.
+};
+
+/**
+ * @brief Header-based dispatcher with a fixed-capacity handler table.
+ *
+ * Usage: register handlers with add() (and optionally set_fallback()), then call start(). After
+ * start() the table is read-only: dispatch() and dispatch_frame() take no lock and may be called
+ * from several threads at once, while add() and set_fallback() fail with Status::InvalidState.
+ * Registration calls are serialized by lock policy @p L.
+ * @tparam N Maximum number of message types.
+ * @tparam L Lock policy protecting registration.
+ */
+template <std::size_t N, typename L = DefaultLock> class Dispatcher {
+    static_assert(N > 0U, "a dispatcher needs room for at least one handler");
+    static_assert(is_lock_policy_v<L>, "L must satisfy the lock policy contract");
+
+public:
+    /// @brief Creates an empty dispatcher for frames laid out as @p layout.
+    explicit Dispatcher(const HeaderLayout& layout) noexcept : layout_(layout) {}
+
+    /**
+     * @brief Registers @p handler for message @p message_id.
+     * @return Status::InvalidState after start(), for an empty handler or an id registered twice;
+     *         Status::CountExceedsMax when the table is full.
+     */
+    Status add(std::uint64_t message_id, MessageHandler handler) noexcept {
+        const ScopedLock<L> guard(lock_);
+        if (started_.load(std::memory_order_relaxed) || !handler || find(message_id) != nullptr) {
+            return Status::InvalidState;
+        }
+        if (count_ == N) {
+            return Status::CountExceedsMax;
+        }
+        array_at(entries_, count_) = Entry{message_id, handler};
+        ++count_;
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Sets the handler for ids without a registered handler.
+     * @return Status::InvalidState after start().
+     */
+    Status set_fallback(FallbackHandler handler) noexcept {
+        const ScopedLock<L> guard(lock_);
+        if (started_.load(std::memory_order_relaxed)) {
+            return Status::InvalidState;
+        }
+        fallback_ = handler;
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Freezes the table; dispatching is possible afterwards.
+     * @return Status::InvalidState when already started.
+     */
+    Status start() noexcept {
+        const ScopedLock<L> guard(lock_);
+        if (started_.load(std::memory_order_relaxed)) {
+            return Status::InvalidState;
+        }
+        sort_entries();
+        started_.store(true, std::memory_order_release);
+        return Status::Ok;
+    }
+
+    /// @brief true after start().
+    [[nodiscard]] bool started() const noexcept { return started_.load(std::memory_order_acquire); }
+
+    /// @brief Number of registered handlers.
+    [[nodiscard]] std::size_t size() const noexcept {
+        const ScopedLock<L> guard(lock_);
+        return count_;
+    }
+
+    /**
+     * @brief Passes @p payload to the handler of message @p message_id.
+     * @return The handler's result; Status::UnknownMessageId when no handler (and no fallback)
+     *         matches; Status::InvalidState before start().
+     */
+    Status dispatch(std::uint64_t message_id, Span<const std::uint8_t> payload) const noexcept {
+        return dispatch(message_id, RawMessage{payload, payload});
+    }
+
+    /**
+     * @brief Passes @p message to the handler of message @p message_id.
+     * @return The handler's result; Status::UnknownMessageId when no handler (and no fallback)
+     *         matches; Status::InvalidState before start().
+     */
+    Status dispatch(std::uint64_t message_id, const RawMessage& message) const noexcept {
+        if (!started()) {
+            return Status::InvalidState;
+        }
+        const Entry* entry = find(message_id);
+        if (entry != nullptr) {
+            counters_.dispatched.increment();
+            return entry->handler(message);
+        }
+        if (fallback_) {
+            counters_.fallback.increment();
+            return fallback_(message_id, message);
+        }
+        counters_.unknown_ids.increment();
+        return Status::UnknownMessageId;
+    }
+
+    /**
+     * @brief Reads the message id from a complete frame and dispatches its payload.
+     * @param frame Header, payload and trailer, as delivered by FrameDecoder.
+     * @return Status::Truncated when @p frame is shorter than header and trailer,
+     * Status::InvalidState when the message id field is outside the header; otherwise as
+     * dispatch().
+     */
+    Status dispatch_frame(Span<const std::uint8_t> frame) const noexcept {
+        const FieldLocation& field = layout_.message_id;
+        if (!valid_width(field.width) || field.offset > layout_.header_size ||
+            layout_.header_size - field.offset < field.width) {
+            return Status::InvalidState;
+        }
+        const std::size_t overhead = layout_.header_size + layout_.trailer_size;
+        if (frame.size() < overhead) {
+            return Status::Truncated;
+        }
+        const std::uint64_t message_id =
+            load_unsigned(frame.subspan(field.offset), field.width, layout_.endian);
+        return dispatch(
+            message_id,
+            RawMessage{frame.subspan(layout_.header_size, frame.size() - overhead), frame});
+    }
+
+    /// @brief Statistics since construction.
+    [[nodiscard]] const DispatchCounters& counters() const noexcept { return counters_; }
+
+private:
+    struct Entry {
+        std::uint64_t message_id = 0U;
+        MessageHandler handler;
+    };
+
+    // Before start(): linear search over the unsorted entries; afterwards: binary search.
+    [[nodiscard]] const Entry* find(std::uint64_t message_id) const noexcept {
+        if (!started_.load(std::memory_order_acquire)) {
+            for (std::size_t index = 0U; index < count_; ++index) {
+                if (array_at(entries_, index).message_id == message_id) {
+                    return &array_at(entries_, index);
+                }
+            }
+            return nullptr;
+        }
+        std::size_t low = 0U;
+        std::size_t high = count_;
+        while (low < high) {
+            const std::size_t middle = low + ((high - low) / 2U);
+            if (array_at(entries_, middle).message_id < message_id) {
+                low = middle + 1U;
+            } else {
+                high = middle;
+            }
+        }
+        return low < count_ && array_at(entries_, low).message_id == message_id
+                   ? &array_at(entries_, low)
+                   : nullptr;
+    }
+
+    // Insertion sort by message id: each entry is rotated into place behind the smaller ids.
+    void sort_entries() noexcept {
+        for (std::size_t index = 1U; index < count_; ++index) {
+            const std::uint64_t moving_id = array_at(entries_, index).message_id;
+            std::size_t position = index;
+            while (position > 0U && array_at(entries_, position - 1U).message_id > moving_id) {
+                --position;
+            }
+            const auto first = entries_.begin();
+            std::rotate(std::next(first, static_cast<std::ptrdiff_t>(position)),
+                        std::next(first, static_cast<std::ptrdiff_t>(index)),
+                        std::next(first, static_cast<std::ptrdiff_t>(index + 1U)));
+        }
+    }
+
+    HeaderLayout layout_;
+    std::array<Entry, N> entries_{};
+    std::size_t count_ = 0U;
+    FallbackHandler fallback_;
+    std::atomic<bool> started_{false};
+    mutable L lock_;
+    mutable DispatchCounters counters_;
+};
+
+/**
+ * @brief Dispatcher for interfaces without a header: every payload goes to one handler.
+ *
+ * Same life cycle as Dispatcher: set_handler(), then start(), then dispatch() from any thread.
+ * @tparam L Lock policy protecting registration.
+ */
+template <typename L = DefaultLock> class RawDispatcher {
+    static_assert(is_lock_policy_v<L>, "L must satisfy the lock policy contract");
+
+public:
+    /**
+     * @brief Creates a dispatcher for frames with @p header_size header bytes before and
+     *        @p trailer_size trailer bytes after the payload (e.g. a checksum).
+     */
+    explicit RawDispatcher(std::size_t trailer_size = 0U, std::size_t header_size = 0U) noexcept
+        : trailer_size_(trailer_size), header_size_(header_size) {}
+
+    /**
+     * @brief Sets the handler of all payloads.
+     * @return Status::InvalidState after start() or for an empty handler.
+     */
+    Status set_handler(MessageHandler handler) noexcept {
+        const ScopedLock<L> guard(lock_);
+        if (started_.load(std::memory_order_relaxed) || !handler) {
+            return Status::InvalidState;
+        }
+        handler_ = handler;
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Freezes the handler; dispatching is possible afterwards.
+     * @return Status::InvalidState when already started.
+     */
+    Status start() noexcept {
+        const ScopedLock<L> guard(lock_);
+        if (started_.load(std::memory_order_relaxed)) {
+            return Status::InvalidState;
+        }
+        started_.store(true, std::memory_order_release);
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Passes @p payload to the handler.
+     * @return The handler's result; Status::UnknownMessageId without a handler;
+     *         Status::InvalidState before start().
+     */
+    Status dispatch(Span<const std::uint8_t> payload) const noexcept {
+        return dispatch(RawMessage{payload, payload});
+    }
+
+    /**
+     * @brief Passes @p message to the handler.
+     * @return The handler's result; Status::UnknownMessageId without a handler;
+     *         Status::InvalidState before start().
+     */
+    Status dispatch(const RawMessage& message) const noexcept {
+        if (!started_.load(std::memory_order_acquire)) {
+            return Status::InvalidState;
+        }
+        if (!handler_) {
+            counters_.unknown_ids.increment();
+            return Status::UnknownMessageId;
+        }
+        counters_.dispatched.increment();
+        return handler_(message);
+    }
+
+    /**
+     * @brief Dispatches a complete frame: everything between header and trailer is the payload.
+     * @return Status::Truncated when @p frame is shorter than header and trailer; otherwise as
+     *         dispatch().
+     */
+    Status dispatch_frame(Span<const std::uint8_t> frame) const noexcept {
+        if (frame.size() < header_size_ + trailer_size_) {
+            return Status::Truncated;
+        }
+        return dispatch(RawMessage{
+            frame.subspan(header_size_, frame.size() - header_size_ - trailer_size_), frame});
+    }
+
+    /// @brief Statistics since construction.
+    [[nodiscard]] const DispatchCounters& counters() const noexcept { return counters_; }
+
+private:
+    std::size_t trailer_size_;
+    std::size_t header_size_;
+    MessageHandler handler_;
+    std::atomic<bool> started_{false};
+    mutable L lock_;
+    mutable DispatchCounters counters_;
+};
+
+} // namespace wireforge
+
+#endif // WIREFORGE_DISPATCHER_HPP

wireforge/_data/runtime/include/wireforge/expr_support.hpp

@@ -0,0 +1,38 @@
+/**
+ * @file expr_support.hpp
+ * @brief Integer helper functions used by generated size and count expressions.
+ *
+ * All operands are `std::int64_t`. In constant expressions an overflow or a division by zero is a
+ * compile error.
+ */
+#ifndef WIREFORGE_EXPR_SUPPORT_HPP
+#define WIREFORGE_EXPR_SUPPORT_HPP
+
+#include <cstdint>
+
+namespace wireforge::expr {
+
+/// @brief Smaller of @p lhs and @p rhs.
+[[nodiscard]] constexpr std::int64_t min(std::int64_t lhs, std::int64_t rhs) noexcept {
+    return rhs < lhs ? rhs : lhs;
+}
+
+/// @brief Larger of @p lhs and @p rhs.
+[[nodiscard]] constexpr std::int64_t max(std::int64_t lhs, std::int64_t rhs) noexcept {
+    return lhs < rhs ? rhs : lhs;
+}
+
+/**
+ * @brief Quotient rounded toward positive infinity.
+ * @param lhs Dividend.
+ * @param rhs Divisor, must not be 0.
+ */
+[[nodiscard]] constexpr std::int64_t ceil_div(std::int64_t lhs, std::int64_t rhs) noexcept {
+    const std::int64_t quotient = lhs / rhs;
+    const bool exact = quotient * rhs == lhs;
+    return exact || ((lhs < 0) != (rhs < 0)) ? quotient : quotient + 1;
+}
+
+} // namespace wireforge::expr
+
+#endif // WIREFORGE_EXPR_SUPPORT_HPP

wireforge/_data/runtime/include/wireforge/frame_decoder.hpp

@@ -0,0 +1,262 @@
+/**
+ * @file frame_decoder.hpp
+ * @brief Extracts complete frames from a byte ring: sync + length, fixed size and length-prefixed
+ *        framing, optional checksum verification and resynchronisation.
+ */
+#ifndef WIREFORGE_FRAME_DECODER_HPP
+#define WIREFORGE_FRAME_DECODER_HPP
+
+#include "wireforge/byte_io.hpp"
+#include "wireforge/checksum.hpp"
+#include "wireforge/frame_layout.hpp"
+#include "wireforge/lock.hpp"
+#include "wireforge/span.hpp"
+#include "wireforge/status.hpp"
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <type_traits>
+
+namespace wireforge {
+
+/// @brief How frame boundaries are found in the byte stream.
+enum class FramingKind : std::uint8_t {
+    Fixed,          ///< Every frame has the same size (an optional sync field is still checked).
+    SyncLength,     ///< A sync field marks the frame start; a length field gives its size.
+    LengthPrefixed, ///< A length field at the frame start gives its size; no sync field.
+};
+
+/// @brief What the length field of a frame counts.
+enum class LengthCounts : std::uint8_t {
+    Payload,           ///< Payload bytes only.
+    PayloadAndTrailer, ///< Payload and trailer bytes.
+    Frame,             ///< The whole frame, header and trailer included.
+};
+
+/// @brief Which bytes a frame checksum covers.
+enum class ChecksumCoverage : std::uint8_t {
+    HeaderAndPayload, ///< From the first header byte to the end of the payload.
+    Payload,          ///< The payload only.
+};
+
+/**
+ * @brief Layout of the frames of one interface.
+ *
+ * Sync and length fields are whole bytes inside the header and use the frame byte order. When the
+ * decoder's checksum type is not NoChecksum, the checksum is a trailer field of the checksum's
+ * size.
+ */
+struct FrameFormat {
+    FramingKind kind;                 ///< Framing method.
+    Endian endian;                    ///< Byte order of the sync, length and checksum fields.
+    std::size_t header_size;          ///< Header bytes.
+    std::size_t trailer_size;         ///< Trailer bytes.
+    std::size_t max_frame_size;       ///< Largest frame; the frame size for FramingKind::Fixed.
+    FieldLocation sync;               ///< Sync field; required for FramingKind::SyncLength.
+    std::uint64_t sync_value;         ///< Expected value of the sync field.
+    FieldLocation length;             ///< Length field; required unless the framing is fixed.
+    LengthCounts length_counts;       ///< Meaning of the length field.
+    std::size_t checksum_offset;      ///< Offset of the checksum inside the trailer.
+    ChecksumCoverage checksum_covers; ///< Bytes covered by the checksum.
+    bool resync; ///< On errors skip one byte and rescan; otherwise drop all buffered bytes.
+};
+
+/// @brief Checksum type meaning "frames carry no checksum".
+struct NoChecksum {};
+
+/// @brief Statistics of a FrameDecoder; readable from any thread.
+struct FrameCounters {
+    RelaxedCounter frames;          ///< Frames delivered.
+    RelaxedCounter discarded_bytes; ///< Bytes dropped while searching for a frame start.
+    RelaxedCounter length_errors;   ///< Frames rejected because of their length field.
+    RelaxedCounter checksum_errors; ///< Frames rejected because of their checksum.
+    RelaxedCounter overflow_errors; ///< Frames that did not fit the output buffer.
+};
+
+/**
+ * @brief Finds frames in a byte ring and copies each complete frame to a caller buffer.
+ *
+ * Incomplete frames stay in the ring until more bytes arrive, so the result does not depend on how
+ * the stream was chunked. The ring must provide `size()`, `capacity()`,
+ * `peek(Span<std::uint8_t>, std::size_t)` and `consume(std::size_t)` (SpscByteRing,
+ * LockedByteRing). Use one decoder per ring, called from the ring's consumer thread.
+ * @tparam Checksum Checksum algorithm of the trailer, or NoChecksum.
+ */
+template <typename Checksum = NoChecksum> class FrameDecoder {
+    static constexpr bool kHasChecksum = !std::is_same_v<Checksum, NoChecksum>;
+    static_assert(!kHasChecksum || is_checksum_v<Checksum>,
+                  "Checksum must be NoChecksum or satisfy the checksum contract");
+
+public:
+    /// @brief Creates a decoder for @p format; check valid() before use.
+    explicit constexpr FrameDecoder(const FrameFormat& format) noexcept : format_(format) {}
+
+    /// @brief true when the format is consistent (field positions, sizes, checksum placement).
+    [[nodiscard]] constexpr bool valid() const noexcept {
+        const FrameFormat& fmt = format_;
+        const std::size_t overhead = fmt.header_size + fmt.trailer_size;
+        const bool sized = fmt.max_frame_size >= overhead && fmt.max_frame_size > 0U;
+        const bool sync_ok =
+            field_ok(fmt.sync) && (fmt.kind != FramingKind::SyncLength || fmt.sync.width != 0U);
+        const bool length_ok =
+            field_ok(fmt.length) && (fmt.kind == FramingKind::Fixed || fmt.length.width != 0U);
+        return sized && sync_ok && length_ok && checksum_ok();
+    }
+
+    /**
+     * @brief Extracts the next frame from @p ring.
+     * @param ring Byte source; bytes of delivered and rejected frames are consumed.
+     * @param out Destination of the frame (header, payload and trailer).
+     * @param[out] frame_size Size of the delivered frame; 0 unless Status::Ok is returned.
+     * @return Status::Ok when a frame was copied to @p out;
+     *         Status::Truncated when more bytes are needed (call again after the next write);
+     *         Status::InvalidLength, Status::ChecksumMismatch or Status::BufferTooSmall when a
+     *         frame was rejected (call again to continue with the following bytes);
+     *         Status::InvalidState when the format is not valid().
+     */
+    template <typename Ring>
+    Status next(Ring& ring, Span<std::uint8_t> out, std::size_t& frame_size) noexcept {
+        frame_size = 0U;
+        if (!valid()) {
+            return Status::InvalidState;
+        }
+        for (;;) {
+            if (ring.size() < format_.header_size || ring.size() == 0U) {
+                return Status::Truncated;
+            }
+            if (!sync_matches(ring)) {
+                counters_.discarded_bytes.add(ring.consume(1U));
+                continue;
+            }
+            std::size_t total = 0U;
+            Status status = frame_length(ring, total);
+            if (status == Status::Ok && ring.capacity() < total) {
+                status = Status::InvalidLength;
+            }
+            if (status != Status::Ok) {
+                counters_.length_errors.increment();
+                return reject(ring, status);
+            }
+            if (ring.size() < total) {
+                return Status::Truncated;
+            }
+            if (out.size() < total) {
+                counters_.overflow_errors.increment();
+                return reject(ring, Status::BufferTooSmall);
+            }
+            const Span<std::uint8_t> frame = out.first(total);
+            static_cast<void>(ring.peek(frame, 0U));
+            if (!checksum_matches(Span<const std::uint8_t>(frame))) {
+                counters_.checksum_errors.increment();
+                return reject(ring, Status::ChecksumMismatch);
+            }
+            static_cast<void>(ring.consume(total));
+            counters_.frames.increment();
+            frame_size = total;
+            return Status::Ok;
+        }
+    }
+
+    /// @brief Statistics since construction or the last reset_counters().
+    [[nodiscard]] const FrameCounters& counters() const noexcept { return counters_; }
+
+    /// @brief Sets every counter to zero.
+    void reset_counters() noexcept {
+        counters_.frames.reset();
+        counters_.discarded_bytes.reset();
+        counters_.length_errors.reset();
+        counters_.checksum_errors.reset();
+        counters_.overflow_errors.reset();
+    }
+
+    /// @brief The format this decoder was created with.
+    [[nodiscard]] constexpr const FrameFormat& format() const noexcept { return format_; }
+
+private:
+    [[nodiscard]] constexpr bool field_ok(const FieldLocation& field) const noexcept {
+        return field.width == 0U ||
+               (valid_width(field.width) && field.offset <= format_.header_size &&
+                format_.header_size - field.offset >= field.width);
+    }
+
+    [[nodiscard]] constexpr bool checksum_ok() const noexcept {
+        if constexpr (kHasChecksum) {
+            return format_.checksum_offset <= format_.trailer_size &&
+                   format_.trailer_size - format_.checksum_offset >= Checksum::kSize;
+        } else {
+            return true;
+        }
+    }
+
+    template <typename Ring>
+    [[nodiscard]] std::uint64_t peek_field(const Ring& ring,
+                                           const FieldLocation& field) const noexcept {
+        std::array<std::uint8_t, kMaxWidth> bytes{};
+        const Span<std::uint8_t> view = Span<std::uint8_t>(bytes).first(field.width);
+        static_cast<void>(ring.peek(view, field.offset));
+        return load_unsigned(Span<const std::uint8_t>(view), field.width, format_.endian);
+    }
+
+    template <typename Ring> [[nodiscard]] bool sync_matches(const Ring& ring) const noexcept {
+        if (format_.sync.width == 0U) {
+            return true;
+        }
+        return peek_field(ring, format_.sync) == format_.sync_value;
+    }
+
+    template <typename Ring>
+    Status frame_length(const Ring& ring, std::size_t& total) const noexcept {
+        const std::size_t overhead = format_.header_size + format_.trailer_size;
+        if (format_.kind == FramingKind::Fixed) {
+            total = format_.max_frame_size;
+            return Status::Ok;
+        }
+        const std::uint64_t length = peek_field(ring, format_.length);
+        if (length > format_.max_frame_size) {
+            return Status::InvalidLength;
+        }
+        const auto value = static_cast<std::size_t>(length);
+        // An if chain: a switch over every LengthCounts value needs a default label that
+        // -Wcovered-switch-default rejects.
+        if (format_.length_counts == LengthCounts::Payload) {
+            total = overhead + value;
+        } else if (format_.length_counts == LengthCounts::PayloadAndTrailer) {
+            total = format_.header_size + value;
+        } else {
+            total = value;
+        }
+        return total >= overhead && total <= format_.max_frame_size ? Status::Ok
+                                                                    : Status::InvalidLength;
+    }
+
+    [[nodiscard]] bool checksum_matches(Span<const std::uint8_t> frame) const noexcept {
+        if constexpr (kHasChecksum) {
+            const std::size_t payload_end = frame.size() - format_.trailer_size;
+            const std::size_t start =
+                format_.checksum_covers == ChecksumCoverage::Payload ? format_.header_size : 0U;
+            const std::uint64_t expected =
+                compute_checksum<Checksum>(frame.subspan(start, payload_end - start));
+            const std::uint64_t received =
+                load_unsigned(frame.subspan(payload_end + format_.checksum_offset), Checksum::kSize,
+                              format_.endian);
+            return expected == received;
+        } else {
+            static_cast<void>(frame);
+            return true;
+        }
+    }
+
+    template <typename Ring> Status reject(Ring& ring, Status status) noexcept {
+        const std::size_t dropped = format_.resync ? ring.consume(1U) : ring.consume(ring.size());
+        counters_.discarded_bytes.add(dropped);
+        return status;
+    }
+
+    FrameFormat format_;
+    FrameCounters counters_;
+};
+
+} // namespace wireforge
+
+#endif // WIREFORGE_FRAME_DECODER_HPP

wireforge/_data/runtime/include/wireforge/frame_layout.hpp

@@ -0,0 +1,20 @@
+/**
+ * @file frame_layout.hpp
+ * @brief Positions of fields inside frame headers and trailers.
+ */
+#ifndef WIREFORGE_FRAME_LAYOUT_HPP
+#define WIREFORGE_FRAME_LAYOUT_HPP
+
+#include <cstddef>
+
+namespace wireforge {
+
+/// @brief Position of a header or trailer field; a width of 0 means "no such field".
+struct FieldLocation {
+    std::size_t offset; ///< Byte offset inside the header (or trailer).
+    std::size_t width;  ///< Width in bytes, 0..8.
+};
+
+} // namespace wireforge
+
+#endif // WIREFORGE_FRAME_LAYOUT_HPP