Docs: add buffer subsystem design rationale

[sgerbino]

Captures the design space and trade-offs for buffer representation, customization, dynamic buffers, and caller/callee ownership patterns in capy's I/O subsystem.

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

• doc/buffer-rationale.md is excluded by !**/doc/**

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1e705294-9ed4-4651-ad11-5ea8bfadfcd5

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

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[cppalliance-bot]

An automated preview of the documentation is available at https://264.capy.prtest3.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-04-14 16:37:02 UTC

[cppalliance-bot]

GCOVR code coverage report https://264.capy.prtest3.cppalliance.org/gcovr/index.html
LCOV code coverage report https://264.capy.prtest3.cppalliance.org/genhtml/index.html
Coverage Diff Report https://264.capy.prtest3.cppalliance.org/diff-report/index.html

Build time: 2026-04-14 16:50:11 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.49%. Comparing base (21ca572) to head (ac5cd70).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #264      +/-   ##
===========================================
+ Coverage    92.47%   92.49%   +0.02%     
===========================================
  Files          168      168              
  Lines         9339     9339              
===========================================
+ Hits          8636     8638       +2     
+ Misses         703      701       -2     

Flag	Coverage Δ
linux	92.46% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 21ca572...ac5cd70. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.