Initial Commit

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

@@ -0,0 +1,28 @@
+# 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.