Document BBR byte units and flight-based delivery rate samples

src/transport_layer/etcp_bbr.h

@@ -43,14 +43,14 @@ enum bbr_bw_probe_cyc { BBR_BW_PROBE_UP = 0, BBR_BW_PROBE_DOWN = 1, BBR_BW_PROBE
 enum bbr_ack_phase    { BBR_ACKS_INIT = 0, BBR_ACKS_REFILLING, BBR_ACKS_PROBE_STARTING, BBR_ACKS_PROBE_FEEDBACK, BBR_ACKS_PROBE_STOPPING };
 
 struct bbr_rate_sample {
-    uint32_t delivered;
-    uint32_t interval_us;
-    uint32_t rtt_us;
-    uint32_t acked_sacked;
-    uint32_t prior_delivered;
-    uint32_t tx_in_flight;
-    int      lost;
-    int      is_app_limited;
+    uint32_t delivered;        // байты, подтверждённые за измерительный интервал; не только текущим ACK
+    uint32_t interval_us;      // max(интервал отправки, интервал доставки), мкс; 0 — нет достоверной оценки скорости
+    uint32_t rtt_us;           // RTT линка, мкс; 0 — пока неизвестен
+    uint32_t acked_sacked;     // новые подтверждённые байты текущего ACK; только они увеличивают общий delivered
+    uint32_t prior_delivered;  // счётчик delivered при отправке подтверждённого пакета, modulo 2^32
+    uint32_t tx_in_flight;     // байты в пути при отправке
+    int      lost;             // потерянные байты с предыдущего ACK
+    int      is_app_limited;   // при отправке не было ожидающих данных приложения
 };
 
 typedef void (*bbr_cwnd_update_fn)(void* ctx, uint32_t new_cwnd);

src/transport_layer/etcp_bbr_doc.md

@@ -37,14 +37,20 @@ bbr_tx_start(&bbr_state);   // вызывать при возобновлени
 ```
 
 ### Интеграция с ETCP_LINK
-BBR создаётся в `etcp_link_new()` как `link->bbr`. `bbr_main()` вызывается в `etcp_handle_ack()` при обработке каждого ACK-пакета. Результаты (cwnd, pacing_rate) записываются в `link->inflight_lim_bytes` и `link->bbr_pacing_rate`. Pacing rate подаётся в traffic shaper линка. `link_id` задаётся в `link->local_link_id` для читаемых логов.
+BBR создаётся в `etcp_link_new()` как `link->bbr`. `etcp_ack_recv()` передаёт новые ACK и измерительный sample.
+Sample использует снимки delivered и времени доставки/отправки, сохранённые в INFLIGHT_PACKET.
+Интервал — максимум времени отправки и подтверждения; ACK одной пачки не создают искусственную сверхскорость.
+`acked_sacked` увеличивает общий счётчик, `delivered` описывает весь интервал и может включать предыдущие ACK.
+Окно применяется через `etcp_link_update_inflight_lim`, pacing — к исходящим DATA.
+ACK-only не ограничивается этим pacing, но проходит общую физическую очередь канала.
 
 ### Тестирование
 Поле `now_tb` позволяет подменять реальное время (`get_time_tb()`) на заданное — при `now_tb == 0` используется `get_time_tb()`, иначе управляемое значение. `on_cwnd_update` — callback для отслеживания изменений cwnd в тестах.
 
 ### Фиксированная точка
 - `BBR_SCALE = 8` — масштаб для gain-коэффициентов (2.77 = 2.77 * 256)
-- `BW_SCALE = 24` — масштаб для bandwidth-значений (bytes/sec * mss)
+- `BW_SCALE = 16` — байты/мкс Q16; повторного умножения на MSS при получении B/s и BDP нет
+- MSS используется для минимального окна. Pacing API ограничен UINT32_MAX B/s, переполнения насыщаются
 - Все внутренние вычисления в фиксированной точке, преобразование в реальные единицы через `bbr_rate_bytes_per_sec()`
 
 ## 3. API
@@ -54,13 +60,13 @@ BBR создаётся в `etcp_link_new()` как `link->bbr`. `bbr_main()` в
 **`struct bbr_rate_sample`** — сэмпл доставки для одного ACK
 | Поле | Назначение |
 |------|-----------|
-| `delivered` | сколько пакетов доставлено этим ACK |
-| `interval_us` | время с предыдущего ACK, мкс |
+| `delivered` | байты, доставленные за измерительный интервал |
+| `interval_us` | max(интервал отправки, интервал доставки), мкс; 0 — нет оценки скорости |
 | `rtt_us` | последний измеренный RTT |
 | `acked_sacked` | байт подтверждено (+SACK) |
 | `prior_delivered` | кумулятивно доставлено до этого ACK (для детекта round) |
 | `tx_in_flight` | inflight на момент отправки подтверждённых пакетов |
-| `lost` | число потерянных пакетов с последнего ACK |
+| `lost` | потерянные байты с последнего ACK |
 | `is_app_limited` | приложение не забивает канал (выходная очередь ниже порога) |
 
 **`struct bbr`** — состояние BBR на линк (подробности в etcp_bbr.h:55-108)