s-netkit 0.0.1__tar.gz

s_netkit-0.0.1/.gitignore

@@ -0,0 +1,50 @@
+# === universal gitignore ===
+
+# OS / IDE
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Sensitive
+.env
+.env.local
+*.key
+*.pem
+secrets/
+private/
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+
+# Node / JS
+node_modules/
+.next/
+dist/
+build/
+
+# Temporary / large
+*.log
+*.tmp
+nul
+NUL
+*.zip
+*.rar
+*.7z
+
+# Media (selectively unignore via !path/*.ext if needed for fixtures)
+*.mp4
+*.mov
+*.avi
+*.mkv
+
+# git worktrees (агентские)
+.worktrees/

s_netkit-0.0.1/.gitlab-ci.yml

@@ -0,0 +1,32 @@
+# Автопубликация на PyPI по семвер-тегу vX.Y.Z через Trusted Publishing (OIDC).
+# Токены НИГДЕ не хранятся: GitLab выдаёт короткоживущий OIDC-токен (PYPI_ID_TOKEN),
+# он одноразово обменивается на PyPI API-токен. Издатель настраивается на pypi.org:
+#   Manage -> Publishing -> GitLab  (namespace=cifropro1/products, project=netkit,
+#   top-level pipeline file=.gitlab-ci.yml, environment — пусто).
+# Дистрибутив на PyPI: s-netkit.
+# Запускается ТОЛЬКО на тег vX.Y.Z (обычный push на main ничего не публикует).
+stages: [publish]
+
+publish-pypi:
+  stage: publish
+  image: ghcr.io/astral-sh/uv:python3.12-bookworm
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+  id_tokens:
+    PYPI_ID_TOKEN:
+      aud: pypi
+  script:
+    - uv build
+    # обмен GitLab OIDC -> одноразовый PyPI API-токен (Trusted Publishing):
+    - |
+      export UV_PUBLISH_TOKEN=$(python3 - <<'PY'
+      import json, os, urllib.request
+      req = urllib.request.Request(
+          "https://pypi.org/_/oidc/mint-token",
+          data=json.dumps({"token": os.environ["PYPI_ID_TOKEN"]}).encode(),
+          headers={"Content-Type": "application/json"},
+      )
+      print(json.load(urllib.request.urlopen(req))["token"])
+      PY
+      )
+    - uv publish

s_netkit-0.0.1/CHANGELOG.md

@@ -0,0 +1,54 @@
+# CHANGELOG — netkit (`s-netkit`)
+
+Формат — [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/);
+версии — [SemVer](https://semver.org/lang/ru/).
+
+## 0.0.1 — выделение сетевого слоя
+
+### Добавлено
+
+- **Кит целиком.** Сетевой слой китов выделен из `librarykit` в отдельный
+  дистрибутив `s-netkit`. Зависимости строго вниз по слоям: `corekit` + `httpx`
+  (+ `stamina` как движок повторов транспорта); `curl-cffi` и `websockets` —
+  опциональные extra.
+- `netkit.transport` — исполнители запроса поверх httpx (async + sync близнец),
+  choke-point `HttpClient`/`SyncHttpClient`, `RestHttpClient`, permissive-рецепты.
+- `netkit.stream` / `netkit.rpc` / `netkit.graphql` — persistent-каналы (WS),
+  codec-слой RPC, GraphQL-клиент.
+- `netkit.limit` / `netkit.retry` — темп (token-bucket `RateLimiter`) и живучесть
+  (header-driven `RetryPolicy`, фиксированная `SimpleRetryPolicy`).
+- `netkit.ladder` — лестница деградации (ступени исполнения и добычи, память
+  ступени, гейт диагностики, события спуска, sync-обёртка).
+- `netkit.pagination` / `netkit.upload` / `netkit.forms` / `netkit.errmap` —
+  листание ресурса, resumable-догрузка, form-кодек, ответ→доменная ошибка.
+- `netkit.contract` — сетевая часть «талии» (`Transport`/`SyncTransport`,
+  `ResponseLike`, `Auth`/`Refreshable`, `Codec`, `StreamTransport`, `ErrorMapper`,
+  `Paginator`) + реэкспорт значений `corekit`.
+- **`netkit.declare` — суть кита:** транспорт ОБЪЯВЛЯЕТСЯ значением
+  (`TransportSpec`: вид `http`/`ws`/`rpc`/`graphql`, адрес, лимит, повторы), а
+  `declare()` отдаёт исполнителя с ЕДИНЫМ поведением лимитов и повторов поверх
+  любого вида. Свой вид добавляется `register_kind()` и получает то же поведение.
+- **`netkit.providers` — реестр слотов.** Всё, что живёт ЭТАЖОМ ВЫШЕ (браузерный
+  минт, каталог профиля движка, склад состояния, межпроцессный лок, полная
+  диагностика, egress `ExecutionContext`, фабрика видов транспорта), приходит
+  сюда СЛОТАМИ, а не импортом — иначе `netkit → browserkit → netkit` замкнулось бы
+  в цикл. Слоты со своим дефолтом никогда не роняют вызов; браузерные слоты
+  дефолта не имеют и поднимают `ProviderMissing` с инструкцией.
+
+### Совместимость
+
+- `librarykit` остаётся ФАСАДОМ: `librarykit.transport`, `librarykit.ladder`,
+  `librarykit.limit`, `librarykit.retry`, `librarykit.errmap`,
+  `librarykit.pagination`, `librarykit.upload`, `librarykit.forms`,
+  `librarykit.rpc`, `librarykit.stream`, `librarykit.graphql` реэкспортируют ТЕ
+  ЖЕ объекты (не копии). Подмодули (`librarykit.transport.http_client`,
+  `librarykit.ladder.minting`, …) сохранены РЕАЛЬНЫМИ модулями — `from pkg.sub
+  import X` и монки-патч по старому пути продолжают работать.
+- `import librarykit` заполняет все слоты `netkit.providers` своими
+  реализациями, поэтому поведение существующих интеграций не меняется.
+
+### Стоимость импорта
+
+- `import netkit` не исполняет ни одного подмодуля (PEP 562): ни httpx, ни
+  stamina, ни asyncio. Закреплено fitness-тестами `tests/test_lazy_facade.py`,
+  включая набор модулей, которые `librarykit` реэкспортирует ЖАДНО.

s_netkit-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

s_netkit-0.0.1/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: s-netkit
+Version: 0.0.1
+Summary: СЕТЕВОЙ слой китов: транспорт (async+sync httpx), WS/RPC/GraphQL, лимиты и повторы, лестница деградации, пагинация, аплоад, form-кодек. Декларативное объявление транспорта с ЕДИНЫМ поведением лимитов и ретраев.
+Author: Dmitry
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: s-corekit>=0.0.1
+Requires-Dist: stamina>=24.3
+Provides-Extra: curl
+Requires-Dist: curl-cffi>=0.7; extra == 'curl'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: ws
+Requires-Dist: websockets>=12.0; extra == 'ws'
+Description-Content-Type: text/markdown
+
+# netkit (`s-netkit`)
+
+**Сетевой слой китов.** Всё, чем интеграция разговаривает с чужим сервером:
+транспорт, темп, живучесть, деградация. Ставится и работает без оркестратора —
+зависимости идут строго вниз: `netkit → corekit`.
+
+```
+     clikit        adapterkit        <- ветки-оболочки
+          \           /
+           librarykit                <- ОРКЕСТРАТОР (сессии, браузер, склад)
+               |
+            netkit                   <- СЕТЬ (этот пакет)
+               |
+            corekit                  <- ОСНОВАНИЕ (значения и правила)
+```
+
+## Что внутри
+
+| модуль | ответственность |
+|---|---|
+| `netkit.transport` | исполнители запроса поверх httpx (async + sync близнец), choke-point `HttpClient`/`SyncHttpClient`, `RestHttpClient` к своему backend, permissive-рецепты |
+| `netkit.stream` | persistent-каналы: `StreamTransport`, WS-реализация (extra `[ws]`) |
+| `netkit.rpc` | codec-слой RPC: `JsonCodec` / `PrefixedJsonCodec` / `RpcClient` |
+| `netkit.graphql` | GraphQL-клиент поверх транспорта кита |
+| `netkit.limit` | `RateLimiter` + token-bucket: ПРОАКТИВНЫЙ темп, а не «поймал 429 — поспал» |
+| `netkit.retry` | политики повторов: header-driven (`RetryPolicy`) и фиксированная (`SimpleRetryPolicy`) |
+| `netkit.ladder` | лестница деградации: чем выполнять запросы и чем добывать состояние, память ступени, события спуска |
+| `netkit.pagination` / `netkit.upload` / `netkit.forms` | листание ресурса, resumable-догрузка, form-urlencoded кодек |
+| `netkit.errmap` | ответ сервера → доменная ошибка (декларативная таблица) |
+| `netkit.declare` | **объявление транспорта** (`http`/`ws`/`rpc`/`graphql`) с ЕДИНЫМ поведением лимитов и повторов |
+| `netkit.providers` | СЛОТЫ верхнего слоя: браузерный минт, склад состояния, диагностика, egress |
+
+## Объявить транспорт декларативно
+
+Один и тот же лимит и одна и та же политика повторов — на любом виде транспорта.
+Интеграция объявляет, а не пишет обвязку:
+
+```python
+from netkit.declare import KIND_HTTP, KIND_WS, TransportSpec, declare
+from netkit.limit import LimitPolicy, LimitScope
+from netkit.retry import SimpleRetryPolicy
+
+limit = LimitPolicy(rate=5, per=1.0)          # 5 обменов в секунду
+retry = SimpleRetryPolicy(backoff=(0.0, 0.0))  # 2 повтора без пауз
+scope = LimitScope(service="acme")
+
+api = declare(TransportSpec(kind=KIND_HTTP, url="https://api.acme.io",
+                            limit=limit, scope=scope, retry=retry))
+live = declare(TransportSpec(kind=KIND_WS, channel=my_ws_channel,
+                            limit=limit, scope=scope, retry=retry))
+
+await api.call("GET", "/v1/items")   # ждёт квоту, повторяет 429/5xx и сбои
+await live.call('{"op":"ping"}')     # ТОТ ЖЕ темп и ТЕ ЖЕ повторы — без своего кода
+```
+
+Свой вид (`grpc`, `sse`, …) добавляется `register_kind(kind, builder)` и сразу
+получает то же поведение.
+
+## Слоты: как netkit зовёт то, что живёт выше
+
+Последняя ступень лестницы поднимает браузер, а браузер — чужой кит, который сам
+зависит от сети. Прямой импорт дал бы цикл, поэтому направление разворачивается:
+netkit **объявляет слот**, верхний слой **заполняет** его на своём импорте.
+
+```python
+from netkit.providers import SLOT_BROWSER_MINT, register_provider
+register_provider(SLOT_BROWSER_MINT, my_mint_session)
+```
+
+Слоты со своим дефолтом (`json_store`, `file_lock`, `state_root`, `path_slug`,
+`transport_factory`, `diagnose`, `egress_proxy`) никогда не роняют вызов — netkit
+умеет их сам, верхний слой лишь уточняет. Слоты без дефолта (браузерные) при
+обращении поднимают `ProviderMissing` с инструкцией: молчаливой деградации
+«ступень тихо ничего не сделала» здесь нет.
+
+Если в окружении стоит `librarykit`, его импорт заполняет все слоты сам —
+отдельная регистрация не нужна.
+
+## Совместимость
+
+`librarykit` остаётся фасадом: `librarykit.transport`, `librarykit.ladder`,
+`librarykit.limit`, `librarykit.retry`, `librarykit.pagination`,
+`librarykit.upload`, `librarykit.forms`, `librarykit.rpc`, `librarykit.stream`,
+`librarykit.graphql`, `librarykit.errmap` реэкспортируют ТЕ ЖЕ объекты (не
+копии) — `isinstance` / `except` / `is` работают через любой из путей.
+
+## Стоимость импорта
+
+`import netkit` не исполняет ни одного подмодуля: ни httpx, ни stamina, ни
+asyncio. Имена резолвятся по PEP 562 при первом обращении — платит тот, кому
+нужно.
+
+## Установка
+
+```bash
+pip install s-netkit          # ядро: corekit + httpx + stamina
+pip install s-netkit[ws]      # + websockets для WS-транспорта
+```

s_netkit-0.0.1/README.md

@@ -0,0 +1,98 @@
+# netkit (`s-netkit`)
+
+**Сетевой слой китов.** Всё, чем интеграция разговаривает с чужим сервером:
+транспорт, темп, живучесть, деградация. Ставится и работает без оркестратора —
+зависимости идут строго вниз: `netkit → corekit`.
+
+```
+     clikit        adapterkit        <- ветки-оболочки
+          \           /
+           librarykit                <- ОРКЕСТРАТОР (сессии, браузер, склад)
+               |
+            netkit                   <- СЕТЬ (этот пакет)
+               |
+            corekit                  <- ОСНОВАНИЕ (значения и правила)
+```
+
+## Что внутри
+
+| модуль | ответственность |
+|---|---|
+| `netkit.transport` | исполнители запроса поверх httpx (async + sync близнец), choke-point `HttpClient`/`SyncHttpClient`, `RestHttpClient` к своему backend, permissive-рецепты |
+| `netkit.stream` | persistent-каналы: `StreamTransport`, WS-реализация (extra `[ws]`) |
+| `netkit.rpc` | codec-слой RPC: `JsonCodec` / `PrefixedJsonCodec` / `RpcClient` |
+| `netkit.graphql` | GraphQL-клиент поверх транспорта кита |
+| `netkit.limit` | `RateLimiter` + token-bucket: ПРОАКТИВНЫЙ темп, а не «поймал 429 — поспал» |
+| `netkit.retry` | политики повторов: header-driven (`RetryPolicy`) и фиксированная (`SimpleRetryPolicy`) |
+| `netkit.ladder` | лестница деградации: чем выполнять запросы и чем добывать состояние, память ступени, события спуска |
+| `netkit.pagination` / `netkit.upload` / `netkit.forms` | листание ресурса, resumable-догрузка, form-urlencoded кодек |
+| `netkit.errmap` | ответ сервера → доменная ошибка (декларативная таблица) |
+| `netkit.declare` | **объявление транспорта** (`http`/`ws`/`rpc`/`graphql`) с ЕДИНЫМ поведением лимитов и повторов |
+| `netkit.providers` | СЛОТЫ верхнего слоя: браузерный минт, склад состояния, диагностика, egress |
+
+## Объявить транспорт декларативно
+
+Один и тот же лимит и одна и та же политика повторов — на любом виде транспорта.
+Интеграция объявляет, а не пишет обвязку:
+
+```python
+from netkit.declare import KIND_HTTP, KIND_WS, TransportSpec, declare
+from netkit.limit import LimitPolicy, LimitScope
+from netkit.retry import SimpleRetryPolicy
+
+limit = LimitPolicy(rate=5, per=1.0)          # 5 обменов в секунду
+retry = SimpleRetryPolicy(backoff=(0.0, 0.0))  # 2 повтора без пауз
+scope = LimitScope(service="acme")
+
+api = declare(TransportSpec(kind=KIND_HTTP, url="https://api.acme.io",
+                            limit=limit, scope=scope, retry=retry))
+live = declare(TransportSpec(kind=KIND_WS, channel=my_ws_channel,
+                            limit=limit, scope=scope, retry=retry))
+
+await api.call("GET", "/v1/items")   # ждёт квоту, повторяет 429/5xx и сбои
+await live.call('{"op":"ping"}')     # ТОТ ЖЕ темп и ТЕ ЖЕ повторы — без своего кода
+```
+
+Свой вид (`grpc`, `sse`, …) добавляется `register_kind(kind, builder)` и сразу
+получает то же поведение.
+
+## Слоты: как netkit зовёт то, что живёт выше
+
+Последняя ступень лестницы поднимает браузер, а браузер — чужой кит, который сам
+зависит от сети. Прямой импорт дал бы цикл, поэтому направление разворачивается:
+netkit **объявляет слот**, верхний слой **заполняет** его на своём импорте.
+
+```python
+from netkit.providers import SLOT_BROWSER_MINT, register_provider
+register_provider(SLOT_BROWSER_MINT, my_mint_session)
+```
+
+Слоты со своим дефолтом (`json_store`, `file_lock`, `state_root`, `path_slug`,
+`transport_factory`, `diagnose`, `egress_proxy`) никогда не роняют вызов — netkit
+умеет их сам, верхний слой лишь уточняет. Слоты без дефолта (браузерные) при
+обращении поднимают `ProviderMissing` с инструкцией: молчаливой деградации
+«ступень тихо ничего не сделала» здесь нет.
+
+Если в окружении стоит `librarykit`, его импорт заполняет все слоты сам —
+отдельная регистрация не нужна.
+
+## Совместимость
+
+`librarykit` остаётся фасадом: `librarykit.transport`, `librarykit.ladder`,
+`librarykit.limit`, `librarykit.retry`, `librarykit.pagination`,
+`librarykit.upload`, `librarykit.forms`, `librarykit.rpc`, `librarykit.stream`,
+`librarykit.graphql`, `librarykit.errmap` реэкспортируют ТЕ ЖЕ объекты (не
+копии) — `isinstance` / `except` / `is` работают через любой из путей.
+
+## Стоимость импорта
+
+`import netkit` не исполняет ни одного подмодуля: ни httpx, ни stamina, ни
+asyncio. Имена резолвятся по PEP 562 при первом обращении — платит тот, кому
+нужно.
+
+## Установка
+
+```bash
+pip install s-netkit          # ядро: corekit + httpx + stamina
+pip install s-netkit[ws]      # + websockets для WS-транспорта
+```

s_netkit-0.0.1/netkit/__init__.py

@@ -0,0 +1,240 @@
+"""netkit — СЕТЕВОЙ слой китов. Всё, чем интеграция ходит наружу.
+
+ФОРМА ГРАФА::
+
+        clikit          adapterkit          <- ветки-оболочки
+             \\             /
+              \\           /
+               librarykit                   <- ОРКЕСТРАТОР (сессии, браузер, склад)
+                    |
+                 netkit                     <- СЕТЬ (транспорт, лимиты, повторы)
+                    |
+                 corekit                    <- ОСНОВАНИЕ (значения и правила)
+
+ЧТО СЮДА ПЕРЕЕХАЛО ИЗ librarykit И ПО КАКОМУ ПРИЗНАКУ. Ровно одно: **модуль
+живёт разговором с чужим сервером**. Не «использует httpx», а именно отвечает за
+доставку, темп и живучесть обмена:
+
+* :mod:`netkit.transport` — исполнители запроса поверх httpx (async + sync
+  близнец), choke-point `HttpClient`/`SyncHttpClient`, REST-клиент к своему
+  backend, permissive-рецепты;
+* :mod:`netkit.stream` — persistent-каналы (WebSocket) — `StreamTransport`;
+* :mod:`netkit.rpc` — codec-слой RPC (`JsonCodec`/`PrefixedJsonCodec`);
+* :mod:`netkit.graphql` — GraphQL-клиент поверх транспорта;
+* :mod:`netkit.limit` — `RateLimiter` + token-bucket (проактивный темп);
+* :mod:`netkit.retry` — политики повторов (header-driven и фиксированная);
+* :mod:`netkit.ladder` — ЛЕСТНИЦА ДЕГРАДАЦИИ: чем выполнять запросы и чем
+  добывать состояние, с памятью ступени и событиями спуска;
+* :mod:`netkit.pagination` / :mod:`netkit.upload` / :mod:`netkit.forms` —
+  листание ресурса, resumable-догрузка, form-urlencoded кодек;
+* :mod:`netkit.errmap` — ответ сервера → доменная ошибка;
+* :mod:`netkit.declare` — ОБЪЯВЛЕНИЕ транспорта (http/ws/rpc/graphql) с ЕДИНЫМ
+  поведением лимитов и повторов поверх любого вида.
+
+ЧЕГО ЗДЕСЬ НЕТ И НЕ БУДЕТ: браузера, антибота, хранилища сессий, keyring,
+шифрования, путей состояния. Всё, что живёт ВЫШЕ, приходит сюда СЛОТАМИ
+(:mod:`netkit.providers`) — не импортом. Поэтому netkit ставится и работает без
+оркестратора, а зависимости идут строго вниз: ``netkit → corekit``.
+
+ЛЕНИВЫЙ ФАСАД. Корень пакета не исполняет НИ ОДНОГО подмодуля: `import netkit`
+не тянет ни httpx, ни stamina, ни asyncio. Имена резолвятся по PEP 562 при
+первом обращении (см. `_LAZY_NAMES` и `__getattr__` ниже) — платит тот, кому
+нужно. Это не украшение: `librarykit` реэкспортирует отсюда десятки имён своими
+жадными импортами, и любой жадный импорт здесь мгновенно вернул бы 264 мс httpx
+в стоимость `import librarykit` (зафиксировано fitness-тестами обоих китов).
+
+СОВМЕСТИМОСТЬ. Ни одно имя отсюда не «переехало» для потребителя: `librarykit`
+и его подмодули (`librarykit.transport`, `librarykit.ladder`, `librarykit.limit`,
+…) реэкспортируют ТЕ ЖЕ объекты (не копии), поэтому ``isinstance``/``except``/
+``is``-сравнения работают через любой из путей.
+"""
+from __future__ import annotations
+
+from importlib import import_module as _import_module
+from importlib.util import find_spec as _find_spec
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover — только статическая видимость для IDE/mypy
+    from typing import Any
+
+__version__ = "0.0.1"
+
+#: Ленивые ИМЕНА: имя в корне → модуль, из которого оно берётся. Все они входят в
+#: `__all__`, поэтому `from netkit import *`, `getattr` и `dir()` видят полную
+#: поверхность, ничего при этом не исполняя.
+_LAZY_NAMES: dict[str, str] = {
+    # contract: формы «талии» сетевого слоя + реэкспорт значений основания
+    "PaginationMode": "netkit.contract",
+    "AuthMode": "netkit.contract",
+    "TransportKind": "netkit.contract",
+    "RequestExecutionMode": "netkit.contract",
+    "DEFAULT_TENANT": "netkit.contract",
+    "SessionRef": "netkit.contract",
+    "ExecutionContext": "netkit.contract",
+    "Creds": "netkit.contract",
+    "RequestBody": "netkit.contract",
+    "QuotaScope": "netkit.contract",
+    "QuotaInfo": "netkit.contract",
+    "LimitSpec": "netkit.contract",
+    "ResponseLike": "netkit.contract",
+    "Transport": "netkit.contract",
+    "SyncTransport": "netkit.contract",
+    "HttpRequestExecutor": "netkit.contract",
+    "SyncHttpRequestExecutor": "netkit.contract",
+    "StreamTransport": "netkit.contract",
+    "Codec": "netkit.contract",
+    "Auth": "netkit.contract",
+    "Refreshable": "netkit.contract",
+    "ProactiveRefreshable": "netkit.contract",
+    "ApplyRefreshable": "netkit.contract",
+    "SyncRefreshable": "netkit.contract",
+    "SyncProactiveRefreshable": "netkit.contract",
+    "ErrorMapper": "netkit.contract",
+    "Paginator": "netkit.contract",
+    # transport: исполнители запроса + choke-point'ы + REST-клиент
+    "HttpxTransport": "netkit.transport",
+    "HttpxRequestExecutor": "netkit.transport",
+    "HttpxSyncTransport": "netkit.transport",
+    "HttpxSyncRequestExecutor": "netkit.transport",
+    "HttpClient": "netkit.transport",
+    "SyncHttpClient": "netkit.transport",
+    "RestHttpClient": "netkit.transport",
+    "NoopAuth": "netkit.transport",
+    "PermissiveErrorMapper": "netkit.transport",
+    "build_permissive_http_client": "netkit.transport",
+    "build_permissive_sync_http_client": "netkit.transport",
+    "aclose_http_client": "netkit.transport",
+    "close_sync_http_client": "netkit.transport",
+    "RefreshCallback": "netkit.transport",
+    # limit / retry: темп и живучесть обмена
+    "LimitWindow": "netkit.limit",
+    "LimitPolicy": "netkit.limit",
+    "LimitScope": "netkit.limit",
+    "RateLimiter": "netkit.limit",
+    "RetryPolicy": "netkit.retry",
+    "DEFAULT_RETRY": "netkit.retry",
+    "SimpleRetryPolicy": "netkit.retry",
+    "DEFAULT_SIMPLE_RETRY": "netkit.retry",
+    # errmap: ответ сервера → доменная ошибка
+    "ErrorMap": "netkit.errmap",
+    "ErrorMapBuilder": "netkit.errmap",
+    "BodyRule": "netkit.errmap",
+    "ExcFactory": "netkit.errmap",
+    "AuthExpired": "netkit.errmap",
+    "build_error_map": "netkit.errmap",
+    "DEFAULT_ERROR_MAP": "netkit.errmap",
+    # rpc / stream / graphql: не-REST виды обмена
+    "JsonCodec": "netkit.rpc",
+    "PrefixedJsonCodec": "netkit.rpc",
+    "RpcClient": "netkit.rpc",
+    "StubStreamTransport": "netkit.stream",
+    "WebSocketsStreamTransport": "netkit.stream",
+    "StreamClosedError": "netkit.stream",
+    "GraphQLClient": "netkit.graphql",
+    # pagination / upload / forms: листание, догрузка, кодек тел
+    "CursorPaginator": "netkit.pagination",
+    "PageParams": "netkit.pagination",
+    "DEFAULT_PAGE_PARAMS": "netkit.pagination",
+    "ItemsExtractor": "netkit.pagination",
+    "CursorExtractor": "netkit.pagination",
+    "default_extract_items": "netkit.pagination",
+    "default_extract_cursor": "netkit.pagination",
+    "with_page_params": "netkit.pagination",
+    "FlatPage": "netkit.pagination",
+    "parse_flat_page": "netkit.pagination",
+    "next_flat_offset": "netkit.pagination",
+    "ChunkedUploader": "netkit.upload",
+    "UploadResult": "netkit.upload",
+    "FormCodec": "netkit.forms",
+    # declare: объявление транспорта + единое поведение лимитов и повторов
+    "TransportSpec": "netkit.declare",
+    "DeclaredTransport": "netkit.declare",
+    "declare": "netkit.declare",
+    "register_kind": "netkit.declare",
+    "kinds": "netkit.declare",
+    "UnknownTransportKind": "netkit.declare",
+    "KIND_HTTP": "netkit.declare",
+    "KIND_WS": "netkit.declare",
+    "KIND_RPC": "netkit.declare",
+    "KIND_GRAPHQL": "netkit.declare",
+    # providers: слоты верхнего слоя (браузер, склад, диагностика, egress)
+    "provider": "netkit.providers",
+    "register_provider": "netkit.providers",
+    "unregister_provider": "netkit.providers",
+    "registered_slots": "netkit.providers",
+    "ProviderMissing": "netkit.providers",
+    "SLOTS": "netkit.providers",
+    "SLOT_BROWSER_MINT": "netkit.providers",
+    "SLOT_BROWSER_PROVIDER": "netkit.providers",
+    "SLOT_ENGINE_PROFILE_DIR": "netkit.providers",
+    "SLOT_TRANSPORT_FACTORY": "netkit.providers",
+    "SLOT_DIAGNOSE": "netkit.providers",
+    "SLOT_EGRESS_PROXY": "netkit.providers",
+    "SLOT_JSON_STORE": "netkit.providers",
+    "SLOT_FILE_LOCK": "netkit.providers",
+    "SLOT_STATE_ROOT": "netkit.providers",
+    "SLOT_PATH_SLUG": "netkit.providers",
+    # ladder: лестница деградации (её поверхность полностью — в netkit.ladder)
+    "TransportLadder": "netkit.ladder",
+    "SyncTransportLadder": "netkit.ladder",
+    "ServiceSpec": "netkit.ladder",
+    "MinterLadder": "netkit.ladder",
+    "ExecutorStep": "netkit.ladder",
+    "MinterStep": "netkit.ladder",
+    "DegradationEvent": "netkit.ladder",
+    "subscribe_degradation": "netkit.ladder",
+    "unsubscribe_degradation": "netkit.ladder",
+    "emit_degradation": "netkit.ladder",
+}
+
+#: Подсказки по extras: модуль → что поставить, если внутри не хватило вендора.
+_EXTRA_HINTS: dict[str, str] = {
+    "netkit.stream": "s-netkit[ws]",
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Ленивый резолв имён корня (PEP 562).
+
+    Порядок: (1) карта ленивых ИМЁН `_LAZY_NAMES`; (2) РЕАЛЬНЫЙ подмодуль с таким
+    именем — чтобы `import netkit; netkit.transport.HttpClient` работало без
+    отдельного импорта подмодуля. Промах — обычная `AttributeError` (иначе
+    `hasattr()` у потребителя взрывался бы вместо возврата False).
+    """
+    target = _LAZY_NAMES.get(name)
+    if target is None:
+        if not name.startswith("_"):
+            try:
+                found = _find_spec(f"{__name__}.{name}") is not None
+            except (ImportError, ValueError):
+                found = False
+            if found:
+                module = _import_module(f"{__name__}.{name}")
+                globals()[name] = module
+                return module
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    try:
+        module = _import_module(target)
+    except ModuleNotFoundError as exc:
+        missing = exc.name or ""
+        if missing.startswith(__name__):
+            raise  # сломан сам кит — не маскируем подсказкой про extras
+        hint = _EXTRA_HINTS.get(target)
+        raise ImportError(
+            f"{name!r} требует модуль {target!r}, но тому не хватает пакета {missing!r}."
+            + (f" Поставь extra: `pip install '{hint}'`." if hint else "")
+        ) from exc
+    value = getattr(module, name)
+    # Кэш в globals(): второй доступ идёт напрямую, мимо хука. Присваивание в dict
+    # атомарно, повторный импорт из другого потока вернёт ТОТ ЖЕ объект из
+    # sys.modules — гонка идемпотентна (важно под free-threading).
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """Полная поверхность корня: жадные атрибуты + `__all__` + ленивые имена."""
+    return sorted(set(globals()) | set(__all__) | set(_LAZY_NAMES))
+
+
+__all__ = ["__version__", *sorted(_LAZY_NAMES)]