docs(054): revise after the pull-model prototype

[lxsaah]

Description

Revises design 054 (zero-allocation connector boundary) with what a throwaway prototype of the pull model showed. The prototype built §4 against main at dfe6adc: InboundDispatch, OutboundRoutes and TopicWriter in core, both MQTT backends, the WebSocket server's outbound path, and the embedded write ring. It was measured but not merged. This PR changes only the design doc.

Every allocation target in §5 held. The doc changes where the code disagreed with it:

• §4.2 outbound pull. The doc defined next() as poll_fn(|cx| self.poll_next(cx)), and that does not compile: poll_next returns a borrow of its state, and a poll_fn closure cannot return one ("captured variable cannot escape FnMut closure body"). The same applies to the select arm in §4.7. The pull now takes two steps, poll_stage then take_staged. New rules:

  • re-poll a route after a skipped value or a lag report, so its waker stays registered;
  • Ready(None) is final, and a select arm must be disabled after it;
  • Pending does not mean every route is empty, because Tokio's cooperative budget can return it with values still ready.

• §4.2 API details. RouteId is a plain usize. RouteInfo carries each route's topic and payload capacities. RouteStats counts skips. The message type is OutboundMessage, because aimdb_core::Outbound already exists. OutboundRoutes is built in build().

• §4.3 topic writer. The doc's closure example fails type inference (E0282) under a generic TopicWriter bound, so the closure form gets its own method, with_topic_fn, beside with_topic_writer. impl From<fmt::Error> for TopicOverflow is added. Overflow is detected by TopicBuf itself, so a writer that ignores the error still has its value skipped.

• §4.7 embedded write ring.

  • The ring only hands out contiguous space. Once its pointers have moved, an empty ring only guarantees about half its capacity: a 2,048-byte ring drained at offset 1,024 cannot grant 1,100 bytes. So the largest frame plus the reserve must fit in capacity / 2, not "the ring minus the reserve".
  • has_room is a probe grant, re-checked on every poll of the arm.
  • The control reserve covers one packet, so PUBACKs wait for room. They are encoded before state.receive, because the PUBACK borrows the client state.
  • The "polling notifier only" claim is wrong: two wakers replace it.
  • Ready(None) is latched. Without that, a session with only inbound links never yields; the idle-session test saw 0 pings.

• §5 / §5.1 measurements.

  Path	Before (main)	Prototype
  Embedded MQTT, one TCP round trip	9 allocs, 302 B, 58.6 µs	0 allocs, 0 B, ~49 µs
  Native MQTT (rumqttc), one round trip	16 allocs, 2,406 B	11 allocs, 557 B
  Core bench rows (§5)	2–3 allocs on the outbound rows	all on target

  A wake-up costs about 80 ns per idle SPMC route on the host. §5 gains a new outbound_next_parked row.

• §4.6, §6, §7, §8.

  • Outage semantics per buffer type are confirmed on the Tokio buffers.
  • The no-compatibility decision is supported: while an ignored with_topic_provider still existed, ten WebSocket tests timed out instead of failing to compile.
  • Two more rejected alternatives are recorded.
  • Open questions are updated, including TCP_NODELAY, which is out of scope for this design.

The prototype's code and its full review page (verdicts, test runs, patch) are not part of this PR. Review page: https://claude.ai/artifact/27gTstCTf72gB7gVmuy8wZ (private until its owner shares it).

Related Issue

• None. Follows docs(design): revise 054 against the tree after 055 #270 and docs(054): drop backward compatibility, two-ring embedded MQTT outbound #271.

Checklist

• I have read the CONTRIBUTING.md document.
• My code follows the project's coding standards. (Docs only.)
• I have added tests to cover my changes. (Not applicable: docs only.)
• All new and existing tests passed (make check). (Not run for this docs-only change. The prototype's suites passed on its own branch; see §5.1.)
• I have updated the documentation accordingly.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HXDnQEx2THUSTASYkThxCw

---

Generated by Claude Code