suaveplan/openspec/archive/2026-05-10-network-plugin-content-delivery-throttle/proposal.md

OpenSpec Change: network-plugin-content-delivery-throttle

• Change ID: network-plugin-content-delivery-throttle
• Package: @suaveplan/network-plugin-content-delivery (extension)
• Status: PROPOSED
• Type: extension
• Date: 2026-05-05

Why

The core network-plugin-content-delivery change shipped the mesh-CDN primitives but deferred BandwidthThrottler — the rate-limiting layer that prevents file transfers from starving CRITICAL control messages. That deferral was per the parent proposal's ## Deferred to follow-up changes block because the throttler couples to @suaveplan/rate-limiter (token-bucket implementation) and to network-plugin-transport-manager (BULK priority class).

This change adds BandwidthThrottler to the existing package without breaking the core surface.

What changes

• ADDED: BandwidthThrottler class wrapping @suaveplan/rate-limiter with chunk-aware semantics (per-peer + global token buckets).
• ADDED: Integration with network-plugin-transport-manager BULK priority — chunk transfers tag every send with priority: "bulk".
• ADDED: cd:throttled event when a chunk dispatch is delayed by the limiter.
• ADDED: ContentDeliveryPlugin.throttler getter wires the new subsystem onto the plugin facade.

Verification approach

• src/throttle/bandwidth-throttler.spec-conformance.test.ts — pins per-peer and global rate enforcement, BULK priority tagging, throttle event emission.

Migration impact

None — additive only.