Add Hotline codec fixtures and tests for wireframe_testing

[leynos]

Summary

• Expand wireframe_testing with comprehensive codec fixtures, unit/integration tests, and BDD-style scenarios for Hotline wire bytes. Also updates to docs and integration surface to surface these fixtures to test authors.

Changes

• Implement codec fixtures in wireframe_testing:
  • New module: wireframe_testing/src/helpers/codec_fixtures.rs
  • Public fixture helpers:
    • valid_hotline_wire, valid_hotline_frame
    • oversized_hotline_wire
    • mismatched_total_size_wire
    • truncated_hotline_header, truncated_hotline_payload
    • correlated_hotline_wire, sequential_hotline_wire
• Wireframe testing integration surface:
  • wireframe_testing/src/helpers.rs now re-exports codec_fixtures and its fixtures
  • wireframe_testing/src/lib.rs re-exports the new fixture functions
• Tests and BDD scaffolding for codec fixtures:
  • New unit/integration tests: tests/codec_fixtures.rs
  • New BDD world/files:
    • tests/features/codec_fixtures.feature
    • tests/fixtures/codec_fixtures.rs
    • tests/steps/codec_fixtures_steps.rs
    • tests/scenarios/codec_fixtures_scenarios.rs
  • Wiring: tests/fixtures/mod.rs, tests/steps/mod.rs, tests/scenarios/mod.rs updated to include the new modules
• Documentation updates:
  • docs/adr-004-pluggable-protocol-codecs.md: Codec test fixtures section added/updated
  • docs/execplans/9-7-2-codec-fixtures-in-wireframe-testing.md: new execution plan document
  • docs/roadmap.md: 9.7.2 marked as done
  • docs/users-guide.md: new Codec test fixtures subsection with usage examples

Why this approach

• Fixtures produce raw wire bytes for compatibility with decoders and test drivers, while providing a convenient valid Frame via a typed wrapper for metadata inspection.
• Hotline-specific fixtures reflect the known wire format, keeping the surface pragmatic for test authors.
• Grouping under a dedicated codec_fixtures module keeps codec-related helpers cohesive with existing encoding/decoding helpers.

Testing plan

• Run unit/integration tests for fixtures:
  • cargo test -p wireframe -- tests/codec_fixtures.rs
• Run the wireframe_testing crate tests:
  • cargo test -p wireframe_testing
• Run the new BDD-style tests and scenarios:
  • cargo test -p wireframe_testing --tests
  • cargo test --all-features -- --test-threads=1 codec_fixtures_scenarios
• Lint/format checks as part of CI (make fmt, make check-fmt, make lint)
• Verify documentation updates compile and docs build passes

Notes

• The new tests exercise decoding of valid frames, rejection on oversized frames, detection of mismatched header fields, behavior on truncated headers/payloads, and transaction-id correlation across frames.
• The changes are additive and backwards compatible.

📎 Task: https://www.devboxer.com/task/8913b8f3-a3be-4300-9a1a-7464825f2d72

[coderabbitai]

Walkthrough

Summarise addition of a public codec fixture suite to wireframe_testing that emits valid, invalid and edge-case Hotline-framed wire bytes and typed frames; adds integration tests, BDD scaffolding, and documentation updates (including a duplicate ADR subsection insertion).

Changes

Cohort / File(s)	Summary
Core Fixture Implementation wireframe_testing/src/helpers/codec_fixtures.rs	Add public fixture types (TransactionId, MaxFrameLength, PayloadLength), HEADER_LEN constant, and builder functions producing Hotline wire bytes and HotlineFrame for: valid, oversized, mismatched total size, truncated header/payload, correlated and sequential multi-frame fixtures; include internal helpers.
Public API Re-exports wireframe_testing/src/helpers.rs, wireframe_testing/src/lib.rs	Declare mod codec_fixtures; and re-export new types and functions (MaxFrameLength, PayloadLength, TransactionId, valid_hotline_wire/frame, oversized_, mismatched_total_size_wire, truncated_, correlated_, sequential_).
Integration Tests tests/codec_fixtures.rs	Add integration test file validating HotlineFrameCodec against the fixture suite; include helpers to assert decode success/failure, frame counts and transaction_id behaviour.
BDD Test Infrastructure tests/fixtures/codec_fixtures.rs, tests/features/codec_fixtures.feature, tests/steps/codec_fixtures_steps.rs, tests/scenarios/codec_fixtures_scenarios.rs	Introduce CodecFixturesWorld (fixture world), BDD feature, step definitions and scenario wiring for valid, oversized, truncated and correlated scenarios.
Test discovery modules tests/fixtures/mod.rs, tests/steps/mod.rs, tests/scenarios/mod.rs	Register new codec_fixtures modules so BDD fixtures, steps and scenarios are discovered by the test harness.
Documentation Updates docs/adr-004-pluggable-protocol-codecs.md, docs/execplans/9-7-2-codec-fixtures-in-wireframe-testing.md, docs/users-guide.md, docs/roadmap.md	Add usage docs and examples for codec fixtures, mark roadmap item 9.7.2 complete; note duplicate ADR subsection was inserted in the diff.

Sequence Diagram(s)

mermaid
sequenceDiagram
participant TestRunner as Test runner
participant Fixtures as wireframe_testing::codec_fixtures
participant Codec as HotlineFrameCodec
participant Decoder as Decoder internals
participant Assertions as Test assertions

TestRunner->>Fixtures: request fixture wire bytes or HotlineFrame
Fixtures-->>TestRunner: return Vec\u003cu8\u003e or HotlineFrame
TestRunner->>Codec: feed bytes to codec.decode
Codec->>Decoder: parse header, validate sizes
alt valid
    Decoder-->>Codec: emit HotlineFrame(s)
    Codec-->>TestRunner: return frames
    TestRunner->>Assertions: verify payloads & transaction IDs
else invalid / truncated / oversized
    Decoder-->>Codec: return error (invalid/missing/trailing bytes)
    Codec-->>TestRunner: return error
    TestRunner->>Assertions: verify error kind/message
end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Document codec testing roadmap #414 — Modifies codec-testing documentation and wireframe_testing helpers; closely related to the new fixture helpers and docs.

Poem

Fixtures sprout where bytes once slept, 🌱
Builders stitch headers, payloads kept,
Valid, fractured, oversized in line,
Correlated IDs march in time,
Tests now hum and codecs rest with pep. ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly relates to the changeset, detailing the fixtures added, test coverage, documentation updates, and testing approach.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Title check	✅ Passed	The title accurately and concisely summarises the main change: adding Hotline codec test fixtures and tests to the wireframe_testing crate.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch add-codec-fixtures-wireframe-tests-mko6da

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sourcery-ai]

Reviewer's Guide

Adds a Hotline-specific codec fixtures module to wireframe_testing, exposes its helpers through the crate’s public surface, and introduces both integration and BDD-style tests plus documentation/ADR/roadmap updates describing and validating these fixtures.

Sequence diagram for using codec fixtures with HotlineFrameCodec

sequenceDiagram
    actor TestAuthor
    participant WireframeTesting as wireframe_testing
    participant CodecFixtures as codec_fixtures
    participant CodecExt as codec_ext
    participant HotlineCodec as HotlineFrameCodec
    participant Decoder as HotlineDecoder

    TestAuthor->>WireframeTesting: valid_hotline_wire(payload, transaction_id)
    WireframeTesting->>CodecFixtures: valid_hotline_wire(payload, transaction_id)
    CodecFixtures-->>WireframeTesting: wire_bytes
    WireframeTesting-->>TestAuthor: wire_bytes

    TestAuthor->>HotlineCodec: new(max_frame_length)
    HotlineCodec-->>TestAuthor: codec

    TestAuthor->>WireframeTesting: decode_frames_with_codec(codec, wire_bytes)
    WireframeTesting->>CodecExt: decode_frames_with_codec(codec, wire_bytes)
    CodecExt->>HotlineCodec: decoder()
    HotlineCodec-->>CodecExt: Decoder

    loop decode_loop
        CodecExt->>Decoder: decode(buffer)
        alt complete_valid_frame
            Decoder-->>CodecExt: Ok(frame)
            CodecExt->>CodecExt: push frame into frames
        else needs_more_bytes
            Decoder-->>CodecExt: Ok(None)
            CodecExt->>CodecExt: break
        else invalid_or_oversized
            Decoder-->>CodecExt: Err(error)
            CodecExt-->>WireframeTesting: Err(error)
            WireframeTesting-->>TestAuthor: Err(error)
            WireframeTesting->>WireframeTesting: return
        end
    end

    CodecExt->>Decoder: decode_eof(buffer)
    alt bytes_remaining
        Decoder-->>CodecExt: Err(bytes_remaining_error)
        CodecExt-->>WireframeTesting: Err(bytes_remaining_error)
        WireframeTesting-->>TestAuthor: Err(bytes_remaining_error)
    else clean_eof
        Decoder-->>CodecExt: Ok(None)
        CodecExt-->>WireframeTesting: Ok(frames)
        WireframeTesting-->>TestAuthor: Ok(frames)
    end

Loading

Class diagram for Hotline codec fixtures module

classDiagram
    direction LR

    class HotlineFrameCodec {
        +new(max_frame_length usize) HotlineFrameCodec
        +decoder() Decoder
        +encoder() Encoder
        +frame_payload(frame HotlineFrame) Bytes
        +wrap_payload(payload Bytes) HotlineFrame
        +correlation_id(frame HotlineFrame) u32
        +max_frame_length() usize
    }

    class HotlineFrame {
        +data_size u32
        +total_size u32
        +transaction_id u32
        +reserved [u8]
        +payload Bytes
    }

    class CodecFixtures {
        <<utility>>
        +valid_hotline_wire(payload u8[], transaction_id u32) Vec_u8
        +valid_hotline_frame(payload u8[], transaction_id u32) HotlineFrame
        +oversized_hotline_wire(max_frame_length usize) Vec_u8
        +mismatched_total_size_wire(payload u8[]) Vec_u8
        +truncated_hotline_header() Vec_u8
        +truncated_hotline_payload(payload_len usize) Vec_u8
        +correlated_hotline_wire(transaction_id u32, payloads u8[][]) Vec_u8
        +sequential_hotline_wire(base_transaction_id u32, payloads u8[][]) Vec_u8
        -build_hotline_wire(payload u8[], transaction_id u32, data_size usize, correct_total_size bool) Vec_u8
        -u32_from_usize(value usize) u32
    }

    class CodecExtHelpers {
        +decode_frames_with_codec(codec HotlineFrameCodec, wire Vec_u8) Result~Vec_HotlineFrame,Error~
        +encode_payloads_with_codec(codec HotlineFrameCodec, payloads Bytes[]) Result~Vec_u8,Error~
        +extract_payloads(frames HotlineFrame[]) Bytes[]
    }

    CodecFixtures ..> HotlineFrameCodec : uses
    CodecFixtures ..> HotlineFrame : constructs
    CodecExtHelpers ..> HotlineFrameCodec : uses
    CodecExtHelpers ..> HotlineFrame : returns

    class WireframeTestingCrate {
        +correlated_hotline_wire
        +mismatched_total_size_wire
        +oversized_hotline_wire
        +sequential_hotline_wire
        +truncated_hotline_header
        +truncated_hotline_payload
        +valid_hotline_frame
        +valid_hotline_wire
        +decode_frames_with_codec
    }

    WireframeTestingCrate ..> CodecFixtures : reexports
    WireframeTestingCrate ..> CodecExtHelpers : reexports

Loading

File-Level Changes

Change	Details	Files
Introduce Hotline codec fixture helpers that construct valid, invalid, truncated, and correlated wire bytes independently of the encoder implementation.	Add codec_fixtures helper module defining HEADER_LEN and helper functions to build Hotline wire frames by manually writing big-endian header fields and payload bytes. Provide valid fixtures returning well-formed wire bytes and a convenience valid_hotline_frame constructor wrapping a payload with a specified transaction_id. Provide invalid fixtures for oversized frames and mismatched total_size, plus truncated header/payload builders that exercise decode_eof and trailing-bytes error paths. Provide correlation fixtures that generate multi-frame byte sequences with shared or sequential transaction IDs, using internal helpers for header/size control and safe usize→u32 conversion.	wireframe_testing/src/helpers/codec_fixtures.rs
Expose the new codec fixtures through the wireframe_testing public API so they are available to downstream tests and examples.	Register codec_fixtures as a helpers submodule and re-export its functions from helpers.rs. Re-export all new fixture functions from the wireframe_testing crate root alongside existing codec helpers.	wireframe_testing/src/helpers.rs wireframe_testing/src/lib.rs
Add integration tests that directly validate each fixture’s decoding behaviour with HotlineFrameCodec.	Create integration tests that ensure valid_hotline_wire decodes to a single frame with expected payload and transaction_id, and valid_hotline_frame sets metadata correctly. Add tests asserting that oversized_hotline_wire and mismatched_total_size_wire produce the expected InvalidData errors from decode_frames_with_codec. Add tests verifying truncated_hotline_header and truncated_hotline_payload yield decode errors containing "bytes remaining" via decode_eof. Add tests asserting correlated_hotline_wire yields frames sharing a transaction_id and sequential_hotline_wire yields frames with incrementing IDs.	tests/codec_fixtures.rs
Introduce rstest-bdd behavioural tests and world/step/scenario wiring for codec fixtures, in line with existing BDD test patterns.	Define a CodecFixturesWorld fixture encapsulating codec configuration, decode execution for each fixture category, and verification helpers for payloads, errors, and transaction IDs. Add rstest-bdd step definitions mapping Gherkin steps to world methods for configuring the codec, decoding each fixture type, and asserting on results. Register scenario functions that bind feature scenarios to the CodecFixturesWorld fixture, with appropriate #[scenario] attributes and clippy #[expect] annotations. Wire the new codec_fixtures modules into the central fixtures/mod.rs, steps/mod.rs, and scenarios/mod.rs so they are compiled and executed with the test suite, and define the codec_fixtures.feature Gherkin file describing four fixture-oriented scenarios.	tests/fixtures/codec_fixtures.rs tests/steps/codec_fixtures_steps.rs tests/scenarios/codec_fixtures_scenarios.rs tests/features/codec_fixtures.feature tests/fixtures/mod.rs tests/steps/mod.rs tests/scenarios/mod.rs
Document the codec fixtures feature and mark the roadmap/design decision as completed, including an execution plan ADR-style document.	Extend the users guide with a "Codec test fixtures" subsection that explains the Hotline fixtures, shows example usage with HotlineFrameCodec and decode_frames_with_codec, and lists each available helper function and its semantics. Update the pluggable protocol codecs ADR with a resolved subsection detailing why fixtures work at the raw Vec level, why they are Hotline-specific, and how they bypass the encoder via manual big-endian header construction. Add an execution plan document for roadmap item 9.7.2 capturing constraints, risks, progress, decisions, and outcomes around adding codec fixtures. Mark roadmap item 9.7.2 as complete by switching its checkbox to [x].	docs/users-guide.md docs/adr-004-pluggable-protocol-codecs.md docs/execplans/9-7-2-codec-fixtures-in-wireframe-testing.md docs/roadmap.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[leynos]

@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix:

tests/codec_fixtures.rs

Comment on file

fn sequential_frames_have_incrementing_ids() -> io::Result<()> {
    let wire = sequential_hotline_wire(10, &[b"x", b"y", b"z"]);
    let codec = hotline_codec();
    let frames = decode_frames_with_codec(&codec, wire)?;

    if frames.len() != 3 {
        return Err(io::Error::other(format!(
            "expected 3 frames, got {}",
            frames.len()
        )));
    }
    let expected_ids: &[u32] = &[10, 11, 12];
    for (i, (frame, expected_id)) in frames.iter().zip(expected_ids.iter()).enumerate() {
        if frame.transaction_id != *expected_id {
            return Err(io::Error::other(format!(
                "frame {i}: expected transaction_id {expected_id}, got {}",
                frame.transaction_id
            )));
        }
    }
    Ok(())
}

❌ New issue: Code Duplication
The module contains 6 functions with similar structure: correlated_frames_share_transaction_id,mismatched_total_size_rejected_by_decoder,oversized_hotline_wire_rejected_by_decoder,sequential_frames_have_incrementing_ids and 2 more functions

[leynos]

@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix:

tests/fixtures/codec_fixtures.rs

Comment on file

    pub fn verify_invalid_data_error(&self) -> TestResult {
        let err = self
            .decode_error
            .as_ref()
            .ok_or("expected a decode error but decoding succeeded")?;
        if !err.to_string().contains("payload too large") {
            return Err(format!("expected 'payload too large' error, got: {err}").into());
        }
        Ok(())
    }

❌ New issue: Code Duplication
The module contains 2 functions with similar structure: CodecFixturesWorld.verify_bytes_remaining_error,CodecFixturesWorld.verify_invalid_data_error

[leynos]

@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix:

wireframe_testing/src/helpers/codec_fixtures.rs

Comment on file

//! Codec fixture functions for generating valid and invalid Hotline-framed

❌ New issue: Primitive Obsession
In this module, 75.0% of all function arguments are primitive types, threshold = 30.0%

[leynos]

@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix:

tests/codec_fixtures.rs

Comment on file

fn sequential_frames_have_incrementing_ids() -> io::Result<()> {
    let wire = sequential_hotline_wire(10, &[b"x", b"y", b"z"]);
    let codec = hotline_codec();
    let frames = decode_frames_with_codec(&codec, wire)?;

    assert_frame_count(&frames, 3)?;

    let expected_ids: &[u32] = &[10, 11, 12];
    for (i, (frame, expected_id)) in frames.iter().zip(expected_ids.iter()).enumerate() {
        if frame.transaction_id != *expected_id {
            return Err(io::Error::other(format!(
                "frame {i}: expected transaction_id {expected_id}, got {}",
                frame.transaction_id
            )));
        }
    }
    Ok(())
}

❌ New issue: Code Duplication
The module contains 2 functions with similar structure: correlated_frames_share_transaction_id,sequential_frames_have_incrementing_ids

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 2500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4b33d12e0f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/execplans/9-7-2-codec-fixtures-in-wireframe-testing.md`:
- Line 431: Replace the British spelling "parameterised" with the Oxford/en-GB
"-ize" form "parameterized" in the sentence containing "raw-byte fixtures rather
than generic `FrameCodec`-parameterised generators" so the documentation follows
the project's en-GB-oxendict guideline; update that token in the
docs/execplans/9-7-2-codec-fixtures-in-wireframe-testing.md content to read
"`FrameCodec`-parameterized generators".

In `@tests/codec_fixtures.rs`:
- Around line 117-137: Replace the manual length check in assert_transaction_ids
with a call to the existing helper assert_frame_count to avoid duplication: call
assert_frame_count(frames, expected_ids.len()) (using the expected_ids.len()
converted as needed) and propagate its Result; then keep the iteration over
frames.zip(expected_ids) to validate transaction_id mismatches and return errors
from the loop as before. Ensure you reference the functions
assert_transaction_ids and assert_frame_count when editing.

In `@tests/fixtures/codec_fixtures.rs`:
- Around line 53-104: Extract the repeated match-and-store logic into a private
helper fn decode_fixture(&mut self, wire: Vec<u8>) -> TestResult that obtains
the codec via self.codec.as_ref().ok_or("codec not configured")? and calls
wireframe_testing::decode_frames_with_codec(codec, wire) storing Ok(frames) into
self.decoded_frames and Err(e) into self.decode_error, then return Ok(()).
Replace the bodies of decode_valid_fixture, decode_oversized_fixture,
decode_truncated_fixture, and decode_correlated_fixture to only build the
appropriate wire (e.g. valid_hotline_wire,
oversized_hotline_wire(codec.max_frame_length()), truncated_hotline_header(),
correlated_hotline_wire(...)) and call self.decode_fixture(wire). Ensure helper
is private and referenced by those methods.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d48237c and 4b33d12.

📒 Files selected for processing (15)

• docs/adr-004-pluggable-protocol-codecs.md
• docs/execplans/9-7-2-codec-fixtures-in-wireframe-testing.md
• docs/roadmap.md
• docs/users-guide.md
• tests/codec_fixtures.rs
• tests/features/codec_fixtures.feature
• tests/fixtures/codec_fixtures.rs
• tests/fixtures/mod.rs
• tests/scenarios/codec_fixtures_scenarios.rs
• tests/scenarios/mod.rs
• tests/steps/codec_fixtures_steps.rs
• tests/steps/mod.rs
• wireframe_testing/src/helpers.rs
• wireframe_testing/src/helpers/codec_fixtures.rs
• wireframe_testing/src/lib.rs

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/execplans/9-7-2-codec-fixtures-in-wireframe-testing.md`:
- Around line 352-358: Update the docs to match the actual decode_eof error
wording: in the examples/tests described by
truncated_header_produces_trailing_bytes_error and
truncated_payload_produces_trailing_bytes_error (which call
truncated_hotline_header and truncated_hotline_payload(100) and then attempt
decode), change the asserted error text from "trailing" to "bytes remaining" to
reflect the decode_eof implementation; make the same replacement in the other
referenced block (the section around the second occurrence, currently lines
391-395) so all documentation matches the current behavior of decode_eof.
- Around line 490-526: Update the documented function signatures to match the
newtype-based public API: change parameters typed as primitives to accept impl
Into<TransactionId> for functions taking transaction_id (valid_hotline_wire,
valid_hotline_frame, correlated_hotline_wire, sequential_hotline_wire), impl
Into<MaxFrameLength> for oversized_hotline_wire, and impl Into<PayloadLength>
for truncated_hotline_payload; leave return types (e.g., HotlineFrame) and
payload slice shapes intact and keep truncated_hotline_header() as-is. Ensure
the doc examples and signature listings use these Into<> types instead of raw
u32/usize so the docs reflect the shipped API.

In `@tests/fixtures/codec_fixtures.rs`:
- Around line 87-95: In decode_fixture, reset the fixture state at the start by
clearing self.decoded_frames and setting self.decode_error = None before calling
wireframe_testing::decode_frames_with_codec; keep the existing codec check (let
codec = self.codec.as_ref().ok_or(...)?), then run the match and assign into
those fields as now so each decode starts with deterministic empty state and no
stale results from prior runs.

In `@wireframe_testing/src/helpers/codec_fixtures.rs`:
- Around line 198-204: The function truncated_hotline_payload currently allows a
claimed payload_len of 0 which yields a header-only (non-truncated) frame;
adjust truncated_hotline_payload to enforce a minimum claimed payload length of
1 by clamping payload_len (or replacing 0 with 1) before computing data_size,
total_size, half_payload and allocating buf (preserve use of variables
payload_len, data_size, total_size, half_payload, HEADER_LEN and the existing
return type) so the generated buffer always represents a truncated payload.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 4b33d12 and fc6a653.

📒 Files selected for processing (4)

• docs/execplans/9-7-2-codec-fixtures-in-wireframe-testing.md
• tests/codec_fixtures.rs
• tests/fixtures/codec_fixtures.rs
• wireframe_testing/src/helpers/codec_fixtures.rs

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (2)

docs/execplans/9-7-2-codec-fixtures-in-wireframe-testing.md (2)

277-319: ⚠️ Potential issue | 🟠 Major

Synchronize documented interfaces with the shipped API.

Replace primitive signatures with impl Into<TransactionId>, impl Into<MaxFrameLength>, and impl Into<PayloadLength> in Stage A. Rename verify_trailing_bytes_error() to verify_bytes_remaining_error() in the Stage C world-method list.

As per coding guidelines: "Use markdown files within the docs/ directory as a knowledge base and source of truth for project requirements, dependency choices, and architectural decisions."

Also applies to: 402-408

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/execplans/9-7-2-codec-fixtures-in-wireframe-testing.md` around lines 277
- 319, Update the documented function signatures in Stage A to match the shipped
API by replacing primitive parameter types with Into wrappers (e.g., change
signatures to use impl Into<TransactionId>, impl Into<MaxFrameLength>, and impl
Into<PayloadLength> for functions like valid_hotline_wire, valid_hotline_frame,
oversized_hotline_wire, mismatched_total_size_wire, truncated_hotline_header,
truncated_hotline_payload, correlated_hotline_wire, and
sequential_hotline_wire), and in Stage C rename the listed world-method
verify_trailing_bytes_error() to verify_bytes_remaining_error() so the docs and
tests match the actual codebase.

---

87-95: ⚠️ Potential issue | 🟡 Minor

Correct the truncated-frame error-path description.

State that truncated inputs surface via decode_eof with "bytes remaining on stream". Remove attribution to the trailing-bytes check in this section.

As per coding guidelines: "Ensure that any API or behavioural changes are reflected in the documentation in docs/."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/execplans/9-7-2-codec-fixtures-in-wireframe-testing.md` around lines 87
- 95, Update the docs to state that truncated-frame inputs from the Hotline
decoder surface via decode_eof with an error message "bytes remaining on stream"
(not via the trailing-bytes check), remove the sentence attributing truncated
inputs to the trailing-bytes path, and explicitly note that
decode_frames_with_codec will report these truncations through decode_eof rather
than the decoder returning Err; reference the Hotline decoder behavior (Ok(None)
on truncated data), decode_frames_with_codec, and the fixture API so BDD tests
and fixtures assert on the decode_eof "bytes remaining on stream" error path.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@wireframe_testing/src/helpers/codec_fixtures.rs`:
- Around line 120-123: Replace unchecked usize additions with saturating
arithmetic to avoid overflow when constructing fixtures: in
oversized_hotline_wire (using MaxFrameLength) change oversized_len =
max_frame_length + 1 to use saturating_add(1); in truncated_hotline_payload
(using PayloadLength and HEADER_LEN) use payload_len.saturating_add(HEADER_LEN)
before calling u32_from_usize; and in build_hotline_wire compute total_size with
data_size.saturating_add(HEADER_LEN) (and for the off-by-one branch apply
another saturating_add(1)) before converting with u32_from_usize. Update all
occurrences in those functions to use saturating_add on usize operands (e.g.,
MAX/sizes) so fixture construction remains panic-free.

---

Duplicate comments:
In `@docs/execplans/9-7-2-codec-fixtures-in-wireframe-testing.md`:
- Around line 277-319: Update the documented function signatures in Stage A to
match the shipped API by replacing primitive parameter types with Into wrappers
(e.g., change signatures to use impl Into<TransactionId>, impl
Into<MaxFrameLength>, and impl Into<PayloadLength> for functions like
valid_hotline_wire, valid_hotline_frame, oversized_hotline_wire,
mismatched_total_size_wire, truncated_hotline_header, truncated_hotline_payload,
correlated_hotline_wire, and sequential_hotline_wire), and in Stage C rename the
listed world-method verify_trailing_bytes_error() to
verify_bytes_remaining_error() so the docs and tests match the actual codebase.
- Around line 87-95: Update the docs to state that truncated-frame inputs from
the Hotline decoder surface via decode_eof with an error message "bytes
remaining on stream" (not via the trailing-bytes check), remove the sentence
attributing truncated inputs to the trailing-bytes path, and explicitly note
that decode_frames_with_codec will report these truncations through decode_eof
rather than the decoder returning Err; reference the Hotline decoder behavior
(Ok(None) on truncated data), decode_frames_with_codec, and the fixture API so
BDD tests and fixtures assert on the decode_eof "bytes remaining on stream"
error path.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fc6a653 and a366bbd.

📒 Files selected for processing (3)

• docs/execplans/9-7-2-codec-fixtures-in-wireframe-testing.md
• tests/fixtures/codec_fixtures.rs
• wireframe_testing/src/helpers/codec_fixtures.rs