feat(stabilization)!: bytesbuf 1.0

[martintmk]

Summary

Adds pending stabilization notes for the bytesbuf crate based on O365 Core work item 7688114. The notes record the proposed BytesBuf, BytesView, owned-buffer I/O, and memory-provider stable boundary, along with deferred low-level APIs and unresolved review items. Also adds an empty docs/DESIGN.md placeholder.

Validation

• just package=bytesbuf format
• just package=bytesbuf readme
• cargo build -p bytesbuf
• cargo test -p bytesbuf
• git diff --check
• GitHub required checks and Codecov passed
• Spellcheck attempted locally, but the installed cargo-spellcheck process exits during startup on this machine; the GitHub spell-check job passed.

Review

• Multi-model review completed with Opus, Sonnet, and GPT reviewers.
• Review findings about feature gates, memory-provider implementation dependencies, and BlockMeta exposure points were addressed.
• Final review found no remaining substantive issues.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.0%. Comparing base (d799037) to head (cf75956).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #645   +/-   ##
=======================================
  Coverage   100.0%   100.0%           
=======================================
  Files         473      473           
  Lines       45493    45493           
=======================================
  Hits        45493    45493           

Flag	Coverage Δ
linux	?
linux-arm	?
scheduled	?
windows	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

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

[martintmk]

Posted by an AI agent

Three non-blocking stabilization gaps remain in the proposed bytesbuf 1.0 checklist; this documentation-only PR leaves the paired public API surface unchanged.

Coverage: API design, correctness, tests, performance, naming, telemetry, resilience, consistency, public API, and public docs all completed at cf75956bf67d44c381889e1900933fa9fdb6417c; the public API comparison was byte-identical.

[martintmk]

Posted by an AI agent · Non-blocking

Memory stabilization omits allocation-failure semantics

Problem
The proposed stable boundary includes Memory, but the checklist does not decide whether reserve remaining infallible - with implementations permitted to panic or abort when capacity is unavailable - is intentional.

Why this matters
Changing this contract after 1.0 to return a typed allocation error would break downstream implementations and callers, while the current shape cannot represent recoverable resource pressure.

Suggested fix
Add an explicit stabilization decision: either document panic/abort as the stable invariant or define a fallible reservation path before 1.0.

[martintmk]

Posted by an AI agent · Non-blocking

The checklist depends on an unavailable approved I/O design

Problem
This item requires validation against "the approved owned-buffer Read/Write design," but the newly added docs/DESIGN.md is empty and no repository document here defines or links that design.

Why this matters
Reviewers cannot independently determine the contract that the writable-slice and vectored-write APIs must satisfy before stabilization.

Suggested fix
Document the approved design in DESIGN.md and link it here, or link the existing authoritative design and remove the empty placeholder.

[martintmk]

Posted by an AI agent · Non-blocking

BytesBufRemaining diverges from the slice-iterator family

Problem
The proposed stable list includes BytesBufRemaining, which is returned by BytesBufVectoredWrite::slices_mut(), while the sibling immutable iterator is named BytesViewSlices.

Why this matters
Stabilizing the current name makes the related immutable and mutable slice iterators harder to discover and understand as one API family.

Suggested fix
Consider renaming it to BytesBufSlicesMut before stabilization and update user-facing references.