Spool

The one sanctioned per-receiver inbound buffer for in-process delivery.

A Spool holds incoming frames for a single receiver, the way a spool of thread feeds a loom — and, like the print-spool sense of the word, it is a bounded producer/consumer queue. Each arriving frame is handed to deliver, and the receiver collects incoming exactly once (single-collection FIFO).

It is generic in the frame type T because kuilt delivers at two layers, both with the same unbounded-growth risk: the multi-peer Seam layer (Spool<Swatch>) and the point-to-point us.tractat.kuilt.core.fabric.Connection transport SPI (Spool<ByteArray>). Both — and any third-party fabric implementor — route delivery through one Spool rather than re-deriving a bounded channel.

It is always bounded — its capacity and overflow behaviour come from the injected DeliveryPolicy (default DeliveryPolicy.Reliable, capacity DeliveryPolicy.DEFAULT_CAPACITY). There is no unbounded Spool: that footgun (an inbound queue growing without backpressure until it exhausts the heap) is structurally unrepresentable.

Overflow behaviour follows the policy:

• SUSPEND suspends the delivering caller until the receiver drains (backpressure).

• DROP_OLDEST / DROP_LATEST never suspend — the channel discards per the policy.

• FAIL throws FrameOverflow when the buffer is genuinely full.

A receiver that closes concurrently (left the mesh) is treated as a drop, not an error — matching best-effort fabric delivery: the frame is simply discarded rather than surfaced to the broadcaster.