docs: state Capy positioning, execution invariant, and interop escape…

[mvandeberg]

… hatch

Addresses #341 and #349: the docs never stated capy's value proposition, its core execution invariant, or its foreign-awaitable escape hatch.

Documentation:

• index.adoc: add "What Capy Is / Is Not" positioning (protocol + reference implementation; the IoAwaitable interop dimension) and an up-front callout of the same-executor invariant.
• 4c.executors.adoc: new "The Same-Executor Invariant" section stating the rule, its rationale, and how affinity/run maintain it.
• 4d.io-awaitable.adoc: frame IoAwaitable as an interop vocabulary and add "Bridging a Foreign Awaitable" documenting the escape hatch (and why there is no universal auto-bridge).
• Two example pages (8o sender bridge, 8p Asio use_capy) plus nav entries.
• Clean up stale xrefs to the removed dynamic-buffer pages.
• Update the IoAwaitable paper reference from draft D4003 to published P4003.

Examples (fix bit-rot from the continuation refactor so the referenced interop examples build and run again):

• use_capy.hpp / uni_stream.hpp / capy_streams.cpp: post a continuation through the executor instead of a raw coroutine_handle.
• use_capy_example.cpp / any_stream.cpp: writer/reader return io_task<> to satisfy when_all's io_result requirement.

[cppalliance-bot]

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

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

2026-07-02 19:53:01 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.29%. Comparing base (fa088fb) to head (f2809e7).
⚠️ Report is 2 commits behind head on develop-2.

Additional details and impacted files

@@            Coverage Diff             @@
##           develop-2     #355   +/-   ##
==========================================
  Coverage      98.29%   98.29%           
==========================================
  Files             77       79    +2     
  Lines           3984     3986    +2     
==========================================
+ Hits            3916     3918    +2     
  Misses            68       68           

Flag	Coverage Δ
linux	98.29% <ø> (+<0.01%)	⬆️

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

---

Continue to review full report in Codecov by Harness.

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

🚀 New features to boost your workflow:

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