Inventory: Frame Vec<u8> bounds, APIs, and plan (issue 287)

[leynos]

Summary

• Adds a dedicated execplan/document for Inventory of Frame = Vec trait bounds, APIs, and coupling points related to issue 287 (supporting epic 284).
• The new document outlines constraints, tolerances, risks, validation, and planned workstreams to bound the scope of a potential Bytes migration.

Change description

• Introduces a new document at docs/execplans/issue-287-inventory-trait-bounds-expecting-frame-vec-u8.md outlining:
  • Purpose and big picture
  • Constraints and how to categorize findings
  • Tolerances/exception triggers
  • Risks and mitigation strategies
  • Validation and acceptance criteria
  • Context from the current repository (evidence of Vec-bound surfaces)
  • Illustrative examples and concrete steps to build the inventory
  • Plan of work (Stages A–E)
  • Interfaces and dependencies to consider
• This is a documentation-only effort that catalogues current coupling to Vec and frames the boundaries for future migration work.

Why this matters

• The repository currently relies on Vec as a de facto frame representation in various public and internal surfaces. This inventory clarifies where those bindings exist, what would be impacted by a Bytes-driven migration, and what generalization paths or risks to consider.
• By codifying evidence and scope, stakeholders can coordinate epic 284 work and roadmap items more effectively.

What to review

• The document structure and taxonomy: frame-bound, payload-bound, internal-only, docs/tests-only.
• Evidence citations: file paths, symbols, and signatures that illustrate Vec coupling.
• Plan stages and concrete steps for creating the inventory document (Stage A–E).
• Open questions and future work suitable for epic 284 linkage.

Validation plan

• This is a documentation-only change; no runtime code is touched. Validation focuses on:
  • Consistency with current repository layout and signatures (src/* references cited in the doc).
  • Clarity and completeness of the inventory workflow.
• If exploratory tests or static checks are added later, follow the guidance in the new document (rstest-ready scaffolding, gating for documentation-only work, etc.).

Impact

• No new dependencies or runtime changes.
• Provides a foundation for future migration planning and alignment with epic 284.

Progress & next steps

• Create inventory execplan document with current evidence points.
• Publish docs/execplans/issue-287-inventory-trait-bounds-expecting-frame-vec-u8.md (this PR).
• Link the inventory document to the relevant epic 284 entry and roadmap items.
• If applicable, add exploratory rstest coverage to validate critical ownership/flow semantics.
• Run documentation quality gates (fmt, markdownlint) as part of CI.

Related context

• The document references concrete evidence found in the repository (e.g., Vec-bound surfaces in middleware, envelope, payload handling, hooks, and frame-related corollaries).
• It also points toward existing design documents that suggest more generic or Bytes-led directions.

Open questions

• Are there additional surfaces to classify beyond the currently cited examples?
• What is the exact epic linkage text to insert once the document is published in the repo?
• Should we create a dedicated roadmap item for this inventory work if none exists?

◳ Generated by DevBoxer ◰

---

ℹ️ Tag @devboxerhub to ask questions and address PR feedback

📎 Task: https://www.devboxer.com/task/c4c4719f-ccbb-4995-9d3e-4e942bfda14c

📝 Closes #284

Summary by Sourcery

Documentation:

• Introduce a new execplan in docs describing the scope, taxonomy, risks, validation strategy, and work plan for cataloguing Vec<u8>-based frame and payload couplings.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4e66b5a0-b159-4858-951c-e06756c60d41

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch inventory-trait-bounds-frame-vec-u8-lm8fpf

---

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

[sourcery-ai]

Reviewer's Guide

Adds a new execplan document that inventories and plans around Frame = Vec<u8> trait bounds and APIs, defining taxonomy, risks, validation steps, and a staged plan to support a future Bytes migration without changing runtime code.

Sequence diagram for current Vec_u8 payload flow through codec, envelope, middleware, and hooks

sequenceDiagram
    participant Codec
    participant PacketParts
    participant Envelope
    participant FrameHandlingResponse
    participant ServiceRequest
    participant ServiceResponse
    participant ClientBeforeSendHook
    participant DLQSender

    Codec->>PacketParts: decode() returns PacketParts{ payload: Vec_u8 }
    PacketParts->>Envelope: new() with payload: Vec_u8
    Envelope-->>FrameHandlingResponse: pass Envelope with payload: Vec_u8
    FrameHandlingResponse->>ServiceRequest: ServiceRequest::new(env.payload, env.correlation_id)
    ServiceRequest-->>ServiceRequest: frame_mut() returns &mut Vec_u8
    ServiceRequest-->>ServiceResponse: processed payload Vec_u8
    ServiceResponse-->>ClientBeforeSendHook: invoke BeforeSendHook(&mut Vec_u8)
    ClientBeforeSendHook-->>ServiceResponse: possibly mutated Vec_u8
    ServiceResponse-->>DLQSender: push_dlq.send(Vec_u8) on error path

Loading

File-Level Changes

Change	Details	Files
Add an execplan markdown document describing how to inventory and classify all Vec<u8>-coupled frame and payload surfaces and how that feeds into a future Bytes migration.	Introduce a purpose and scope section for issue 287 and its relationship to epic 284, clarifying that the work is an inventory and planning effort rather than the migration itself. Define constraints, tolerances, risks, validation and acceptance criteria, including concrete CI commands and optional rstest usage for any exploratory tests added later. Document current evidence of Vec<u8> coupling across middleware, envelopes, frame handling, builders, hooks, correlation traits, and existing design docs, with guidance on classification as frame-bound, payload-bound, internal-only, or docs/tests-only. Lay out a staged plan of work (Stages A–E) with concrete steps for scanning the codebase, classifying findings, tracing runtime flows, optionally adding tests, and updating epics/roadmap entries. Add supporting sections for exploratory testing strategy, interfaces and dependencies, idempotence and recovery, progress tracking, surprises & discoveries, decision log, and outcomes/retrospective to keep the execplan as a living document.	docs/execplans/issue-287-inventory-trait-bounds-expecting-frame-vec-u8.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#284	Produce a design proposal for a Bytes-based Frame API (e.g., Bytes-only vs dual support), including options, risks, and trade-offs for migrating from Vec.	❌	The PR adds an execplan document that inventories where Frame/Vec assumptions exist and how to catalog them. It does not propose a concrete Bytes-based Frame design or compare design options, nor does it analyze trade-offs of Bytes vs alternatives.
#284	Document a migration and compatibility strategy for downstream users, including a release/rollout plan for the breaking change and a migration guide outline for a major version bump.	❌	The PR focuses on planning an internal inventory of Vec-bound surfaces and scoping future work. It does not describe how downstream users should migrate, does not define compatibility strategies, and does not specify a release or rollout plan for the breaking change.
#284	Define a benchmarking plan and baseline measurements to validate zero-copy decoding and performance goals for the Bytes-based Frame API.	❌	The PR does not mention benchmarks, performance goals, or measurement methodology. It only introduces a documentation plan for cataloguing current Vec couplings and does not specify any benchmarking plan or baseline metrics.

Possibly linked issues

• Analysis: Inventory trait bounds expecting Frame = Vec<u8> #287: PR provides the requested documentation and inventory of Vec-based frame constraints, updating scope beyond BoxedFrameProcessor.
• Epic: Zero-copy frame API (breaking) – adopt Bytes as Frame #284: The PR’s execplan inventories Vec frame usages and defines workstreams directly supporting the Bytes migration epic.

---

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.