Docs 3.5.8 Pull-Up

Co-Authored-By: brekotis <93345790+brekotis@users.noreply.github.com>

docs/Architecture/Model/MODEL.en.md

@@ -57,12 +57,14 @@ Refill works asynchronously and should not block hot routing paths.
 `Registry` is the routing index between ME and client sessions:
 - `conn_id -> client response channel`
 - `conn_id <-> writer_id` binding map
+- writer send routes and their replacement state
 - writer activity snapshots and idle tracking
 
 Main invariants:
 - A `conn_id` routes to at most one active response channel.
 - Writer loss triggers safe unbind/cleanup and close propagation.
 - Registry state is the source of truth for active ME-bound session mapping.
+- The registry binding lock linearizes client binds, writer publication, and the transition that closes a replacement victim to new binds.
 
 ## Adaptive Floor
 
@@ -100,7 +102,9 @@ Goals:
 ### Transition intent
 - `Warm -> Active`: when coverage/readiness conditions are satisfied.
 - `Active -> Draining`: on generation swap, endpoint replacement, or controlled retirement.
-- `Draining -> removed`: after drain TTL/force-close policy (or when naturally empty).
+- `Draining -> removed`: when naturally empty, at the effective force-close deadline, or through threshold/control-path eviction. `me_pool_drain_ttl_secs` is a warning threshold and force-close lower bound, not a removal deadline by itself.
+
+Writer replacement is a separate registry-local lifecycle: `Open -> Preparing -> Retiring`. `Preparing` excludes duplicate replacement work but intentionally permits new client binds. Commit revalidates the victim under the binding lock; `Retiring` rejects new binds. Dropping an uncommitted reservation restores `Open`, while the writer's contour remains independently `Warm`, `Active`, or `Draining`.
 
 This separation reduces SPOF and keeps cutovers predictable.
 
@@ -111,14 +115,17 @@ Generation isolates pool epochs during reinit/reconfiguration.
 ### Lifecycle phases
 1. `Bootstrap`: initial writers are established.
 2. `Warmup`: next generation writers are created and validated.
-3. `Activation`: generation promoted to active when coverage gate passes.
-4. `Drain`: previous generation becomes draining, existing sessions are allowed to finish.
-5. `Retire`: old generation writers are removed after graceful rules.
+3. `Activation`: generation is promoted atomically when the configured coverage ratio and stale-binding policy pass commit-time revalidation.
+4. `Drain`: policy-eligible old writers remain as bounded stale fallback; covered old writers become ineligible and enter retirement during the commit, then may close immediately after it returns.
+5. `Retire`: draining writers are removed when empty or by force-close, threshold, or explicit control policy.
 
 ### Operational guarantees
-- No partial generation activation without minimum coverage.
-- Existing healthy client sessions should not be dropped just because a new generation appears.
-- Draining generation exists to absorb in-flight traffic during swap.
+- Activation is atomic, but the committed topology may still have missing DC-family groups when `me_pool_min_fresh_ratio` passes and `me_bind_stale_mode` permits bounded stale fallback. Mode `never` rejects any missing group.
+- Generation handover is policy-bound, not universally zero-drop: covered old writers may be retired and their bound sessions closed immediately after commit, while only selected stale writers remain available for uncovered groups.
+- A pending generation owns only writers accepted for its generation and current endpoint map; stale tasks cannot publish into a newer generation.
+- A pending generation is keyed by desired-map hash and endpoint revision and may be reused for up to 1800 seconds before expiring.
+- Writer replacement prepares a successor; under one binding guard, commit first moves the predecessor to `Retiring` and then registers the successor before releasing the guard. Failed or cancelled preparation before that boundary preserves the predecessor and releases the reservation.
+- Pool-state telemetry exposes pending writer count and deficit, missing DC-family groups, map currency, orphan warm writers, and replacement `preparing`/`retiring` counts.
 
 ### Readiness and admission
 Pool readiness is not equivalent to “all endpoints fully saturated”.
@@ -149,8 +156,9 @@ Architectural rule:
 
 ### Ownership Model
 Ownership is centered around explicit state domains:
-- `MePool` owns writer lifecycle and policy state.
-- `Registry` owns per-connection routing bindings.
+- `MePool` owns writer inventory, contour lifecycle, and runtime policy state.
+- The reinit coordinator owns active/pending generation authority keyed by map hash and endpoint revision.
+- `Registry` owns per-connection routing bindings, writer send routes, and writer replacement state.
 - `Writer task` owns outbound ME socket send progression.
 - `Reader task` owns inbound ME socket parsing and event dispatch.
 
@@ -188,6 +196,8 @@ Data Plane should avoid waiting on operations that are not strictly required for
 - Shared maps use fine-grained, short-lived locking.
 - Read-mostly paths avoid broad write-lock windows.
 - Backpressure decisions are localized at route/channel boundary.
+- Generation and replacement commits use the lock order `writers -> registry binding -> reinit coordinator`.
+- After acquiring the registry publication guard, a commit has no cancellation point before publication and retirement state are made consistent.
 
 Design target:
 - A slow consumer should degrade only itself (or its route), not global writer progress.
@@ -196,6 +206,7 @@ Design target:
 Writer and reader loops are cancellation-aware:
 - explicit cancel token / close command support;
 - safe unbind and cleanup via registry;
+- RAII replacement reservations restore `Preparing` to `Open` when preparation is cancelled before commit;
 - deterministic order: stop admission -> drain/close -> release resources.
 
 ## Consistency Model
@@ -208,9 +219,10 @@ For one `conn_id`:
 
 ### Generation Consistency
 Generational consistency guarantees:
-- New generation is not promoted before minimum coverage gate.
-- Previous generation remains available in `draining` state during handover.
-- Forced retirement is policy-bound (`drain ttl`, optional force-close), not immediate.
+- Commit revalidates generation, desired-map hash, endpoint revision, and fresh coverage while holding the publication barriers.
+- Promotion requires `me_pool_min_fresh_ratio`; missing DC-family groups additionally require a stale-binding mode other than `never`.
+- Previous-generation writers are retained only where the selected stale-fallback policy requires them. Covered writers become ineligible at commit and may close immediately afterward.
+- Draining writers are removed when empty, at the effective force-close deadline (`0` first selects the 300-second safety fallback, then the drain TTL remains a lower bound), or by threshold/control-path eviction; drain TTL alone only triggers warnings.
 
 ### Policy Consistency
 Policy changes (`adaptive/static floor`, fallback mode, retries) should apply without violating established active-session routing invariants.

docs/Architecture/Model/MODEL.ru.md

@@ -57,12 +57,14 @@ Refill работает асинхронно и не должен блокиро
 `Registry` — маршрутизационный индекс между ME и клиентскими сессиями:
 - `conn_id -> канал ответа клиенту`;
 - map биндов `conn_id <-> writer_id`;
+- send routes writer-ов и их replacement state;
 - снимки активности writer-ов и idle-трекинг.
 
 Ключевые инварианты:
 - один `conn_id` маршрутизируется максимум в один активный канал ответа;
 - потеря writer-а приводит к безопасному unbind/cleanup и отправке close;
 - именно `Registry` является источником истины по активным ME-биндам.
+- binding lock registry линеаризует client binds, публикацию writer-а и переход, закрывающий replacement victim для новых binds.
 
 ## Adaptive Floor
 
@@ -100,7 +102,9 @@ Refill работает асинхронно и не должен блокиро
 ### Логика переходов
 - `Warm -> Active`: когда достигнуты условия покрытия/готовности.
 - `Active -> Draining`: при swap поколения, замене endpoint или контролируемом выводе.
-- `Draining -> removed`: после drain TTL/force-close политики (или естественного опустошения).
+- `Draining -> removed`: после естественного опустошения, при effective force-close deadline либо через threshold/control-path eviction. `me_pool_drain_ttl_secs` — порог предупреждений и нижняя граница force-close, а не самостоятельный deadline удаления.
+
+Writer replacement имеет отдельный registry-local lifecycle: `Open -> Preparing -> Retiring`. `Preparing` исключает дублирующую replacement work, но намеренно разрешает новые client binds. Commit повторно проверяет victim под binding lock; `Retiring` отклоняет новые binds. Отмена незакоммиченного reservation возвращает `Open`, а contour writer-а независимо остаётся `Warm`, `Active` или `Draining`.
 
 Такое разделение снижает SPOF-риски и делает cutover предсказуемым.
 
@@ -111,14 +115,17 @@ Generation изолирует эпохи пула при reinit/reconfiguration.
 ### Фазы жизненного цикла
 1. `Bootstrap`: поднимается начальный набор writer-ов.
 2. `Warmup`: создаётся и валидируется новое поколение.
-3. `Activation`: новое поколение становится active после прохождения coverage-gate.
-4. `Drain`: предыдущее поколение переводится в draining, текущим сессиям дают завершиться.
-5. `Retire`: старое поколение удаляется по graceful-правилам.
+3. `Activation`: generation атомарно становится active после commit-time проверки настроенной доли coverage и stale-binding policy.
+4. `Drain`: подходящие по policy старые writers сохраняются как ограниченный stale fallback; покрытые старые writers становятся недоступны для новых binds и входят в retirement во время commit, после чего могут закрыться сразу по его завершении.
+5. `Retire`: draining writers удаляются после опустошения либо по force-close, threshold или явной control policy.
 
 ### Операционные гарантии
-- нельзя активировать поколение частично без минимального покрытия;
-- healthy-клиенты не должны теряться только из-за появления нового поколения;
-- draining-поколение служит буфером для in-flight трафика во время swap.
+- activation атомарна, но committed topology может содержать отсутствующие DC-family groups, если достигнут `me_pool_min_fresh_ratio` и `me_bind_stale_mode` разрешает ограниченный stale fallback. Режим `never` запрещает отсутствующие groups;
+- generation handover ограничен policy и не даёт универсальной zero-drop гарантии: покрытые старые writers могут retire с закрытием их sessions сразу после commit, а для непокрытых groups сохраняются только выбранные stale writers;
+- pending generation владеет только writer-ами, принятыми для её generation и текущей endpoint map; устаревшие задачи не могут публиковать состояние в более новую generation;
+- pending generation привязана к desired-map hash и endpoint revision и переиспользуется не более 1800 секунд;
+- replacement сначала подготавливает successor; под единым binding guard commit сначала переводит predecessor в `Retiring`, а затем регистрирует successor до освобождения guard. Неудачная или отменённая до этой границы подготовка сохраняет predecessor и освобождает reservation;
+- pool-state telemetry публикует число и дефицит pending writers, отсутствующие DC-family groups, актуальность map, orphan warm writers и счётчики фаз replacement `preparing`/`retiring`.
 
 ### Готовность и приём клиентов
 Готовность пула не равна "все endpoint полностью насыщены".
@@ -149,8 +156,9 @@ Runtime специально разделён на две плоскости:
 
 ### Модель владения состоянием
 Владение разделено по доменам:
-- `MePool` владеет жизненным циклом writer-ов и policy-state.
-- `Registry` владеет routing-биндами клиентских сессий.
+- `MePool` владеет inventory writer-ов, contour lifecycle и runtime policy state.
+- Reinit coordinator владеет authority active/pending generation, привязанной к map hash и endpoint revision.
+- `Registry` владеет routing-биндами клиентских сессий, send routes writer-ов и replacement state.
 - `Writer task` владеет исходящей прогрессией ME-сокета.
 - `Reader task` владеет входящим парсингом и dispatch-событиями.
 
@@ -188,6 +196,8 @@ Data Plane не должен ждать операций, не критичны
 - Для shared map используются короткие и узкие lock-секции.
 - Read-heavy пути избегают длительных write-lock окон.
 - Решения по backpressure локализованы на границе route/channel.
+- Generation и replacement commits используют порядок locks `writers -> registry binding -> reinit coordinator`.
+- После получения registry publication guard до согласованной публикации и retirement state нет cancellation point.
 
 Цель:
 - медленный consumer должен деградировать локально, не останавливая глобальный прогресс writer-а.
@@ -196,6 +206,7 @@ Data Plane не должен ждать операций, не критичны
 Reader/Writer loop должны быть cancellation-aware:
 - явные cancel token / close command;
 - безопасный unbind/cleanup через registry;
+- RAII replacement reservations возвращают `Preparing` в `Open`, если подготовка отменена до commit;
 - детерминированный порядок: stop admission -> drain/close -> release resources.
 
 ## Модель согласованности
@@ -208,9 +219,10 @@ Reader/Writer loop должны быть cancellation-aware:
 
 ### Согласованность поколения
 Гарантии generation:
-- новое поколение не активируется до прохождения минимального coverage-gate;
-- предыдущее поколение остаётся в `draining` на время handover;
-- принудительный вывод writer-ов ограничен policy (`drain ttl`, optional force-close), а не мгновенный.
+- commit повторно проверяет generation, desired-map hash, endpoint revision и fresh coverage под publication barriers;
+- promotion требует `me_pool_min_fresh_ratio`; отсутствующие DC-family groups дополнительно требуют stale-binding mode, отличного от `never`;
+- writers предыдущей generation сохраняются только там, где их требует выбранная stale-fallback policy. Покрытые writers становятся недоступны для новых binds при commit и могут закрыться сразу после него;
+- draining writers удаляются после опустошения, при effective force-close deadline (`0` сначала выбирает safety fallback 300 секунд, после чего drain TTL остаётся нижней границей) либо по threshold/control-path eviction; один drain TTL только вызывает предупреждения.
 
 ### Согласованность политик
 Изменение policy (`adaptive/static floor`, fallback mode, retries) не должно ломать инварианты маршрутизации уже активных сессий.