s-ormkit 0.0.1__tar.gz → 0.2.1__tar.gz

s_ormkit-0.2.1/AGENTS.md

@@ -0,0 +1,45 @@
+# AGENTS.md — ormkit
+
+> Контекст для AI-ассистентов (Claude Code, ChatGPT, Cursor и т.п.), работающих
+> над этим проектом.
+
+## Что это
+
+(заполнить one-line)
+
+## Atlas
+
+Проект зарегистрирован в Atlas-БД (Atlas). Карточка:
+
+```sh
+atlas project get ormkit
+```
+
+Любые изменения метаданных (приоритет, статус, теги) — через atlas CLI:
+
+- `atlas project update ormkit --priority P0` — поменять приоритет
+- `atlas project tag add ormkit -t domain:<slug>` — добавить тег
+- `atlas project move ormkit --to-type <type>` — конвертировать тип
+
+## Тип / Статус (на момент создания)
+
+- type=`kit`, status=`experiment`, priority=`P2`
+
+## Правила работы
+
+- Все исходные тексты, документы, код проекта — в этом репо.
+- Чувствительные данные (`.env`, токены, ключи) — игнорируются `.gitignore`.
+- AI-ассистенту разрешено: читать, генерировать, редактировать в этом репо.
+
+## Канонические команды
+
+- `atlas project get ormkit` — карточка проекта
+- `atlas task list --project ormkit` — задачи проекта (когда W7
+  волна будет реализована)
+
+<!-- atlas:usage:start -->
+## Управление проектом — через Atlas
+
+Этот проект ведётся в Atlas (личная PM-система портфеля). Для задач/проектов/эпиков/бэкапов
+используй CLI `atlas` и вызывай навык `atlas` — вся логика и роутинг внутри навыка.
+<!-- atlas:usage:end -->

s_ormkit-0.2.1/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+Все значительные изменения этого проекта будут документироваться в этом файле.
+
+Формат основан на [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+и этот проект соответствует [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.1] - 2026-08-30
+
+### Добавлено
+
+- `make_async_engine(..., sqlite_pragmas=...)` — дополнительные PRAGMA на каждое
+  подключение sqlite (`journal_mode=WAL`, `busy_timeout`). Нужны там, где одну
+  базу держат несколько процессов: по умолчанию писатель блокирует читателей
+  целиком, и соседний процесс получает «database is locked» ровно в момент
+  чужой записи. Знание общее для любого потребителя sqlite — жило в каждом
+  приложении заново.
+- `make_async_engine(..., connect_args=...)` — параметры драйвера как есть. Для
+  sqlite важно вместе с `busy_timeout`: `aiosqlite` ждёт очереди по своему
+  таймеру (5 с по умолчанию) и отказывает раньше, чем сработает PRAGMA.
+
+Своё поведение не изменилось: `foreign_keys=True` по-прежнему включает внешние
+ключи, а свои PRAGMA добавляются к нему, а не вместо.
+
+## [0.2.0] - 2026-08-17
+
+Кит перестал быть «синхронным ядром с async-хвостами»: асинхронные потребители
+(ChatRelay, в перспективе Skillery) садятся на него без обходных путей.
+
+### Added
+
+- **Async-слой** (`ormkit.async_engine`): `make_async_engine(url|env|default, echo=,
+  foreign_keys=)`, `make_async_session_factory` (`async_sessionmaker`,
+  `expire_on_commit=False`), `init_schema_async` / `drop_schema_async` /
+  `dispose_engine_async`. Для sqlite `PRAGMA foreign_keys=ON` вешается событием на
+  `sync_engine`; `create_async_engine` остаётся ленивым (движок к недоступному
+  postgres создаётся без коннекта).
+- **Асинхронные близнецы** с тем же API, что у синхронных: `AsyncUnitOfWork`
+  (`async with`, rollback при исключении, явный `commit`), `AsyncBaseRepository`
+  (`add / get / get_or_none / list / update / remove / count`), DIP-контракты
+  `AsyncRepositoryProtocol` / `AsyncUnitOfWorkProtocol`.
+- **Резолв DB-URL и автоподстановка драйвера** (`ormkit.url`): `resolve_db_url`
+  (аргумент → env → default), `async_driver_url` (`sqlite`→`aiosqlite`,
+  `postgresql`→`asyncpg`, `mysql`→`aiomysql`), `sync_driver_url`
+  (`postgresql`→`psycopg`). Явно заданный драйвер не трогается; `postgres://`
+  канонизируется в `postgresql://`.
+- **Миграции** (`ormkit.migrations`, extra `[migrations]`): `scaffold_alembic(...)`
+  генерирует в проекте-потребителе `alembic.ini` + `alembic/env.py` (async-движок,
+  `render_as_batch=True`, metadata по ссылке `pkg.module:attr`) + `script.py.mako`;
+  URL резолвится тем же способом, что и в `make_engine` (`migration_url`).
+  CLI: `python -m ormkit migrations init . --metadata myapp.models:Base`
+  (и console script `ormkit`). Без установленного alembic — понятная ошибка
+  `require_alembic` с подсказкой про extra.
+- **Защита от N+1** (`ormkit.loading`): `LoadSpec(selectin=, joined=)` с вложенными
+  путями через точку + `apply_load_spec`; строгий режим на `raiseload("*")` —
+  `strict_loading` (один запрос), `enable_strict_loading` (сессия, с возвратом
+  выключателя), `make_strict_session_factory` / `make_strict_async_session_factory`
+  (фабрики для тестов и CI). Оба репозитория применяют `load_spec` ко всем чтениям.
+
+### Changed
+
+- `make_engine` использует общий резолвер URL и подставляет синхронный драйвер
+  (`postgresql://` → `postgresql+psycopg://`).
+- `BaseRepository` читает через внутренний `_select()` (точка расширения + место
+  применения `load_spec`); публичное поведение не изменилось.
+
+### Notes
+
+- **Обратная совместимость сохранена**: весь синхронный API v0.1.0 на месте,
+  `load_spec` по умолчанию `None` (запросы такие же, как раньше).
+- Alembic НЕ добавлен в обязательные зависимости: `pip install s-ormkit[migrations]`.
+- Тесты постгреса не требуют живого сервера: проверяются резолв URL, ленивое
+  создание движка и offline-рендер миграции (`alembic upgrade head --sql`).
+  Реальный прогон миграций (autogenerate → upgrade → downgrade) — на sqlite+aiosqlite.
+
+## [0.1.0] - 2026-07-07
+
+### Added
+
+- **`ormkit.pagination`** — offset-пагинация: чистые `Page[T]` / `page_to_offset`
+  + SQL-исполнитель `paginate_stmt(session, stmt, limit, offset, count_stmt=,
+  scalars=)` (limit/offset + авто-count, либо custom count для JOIN/DISTINCT).
+- **`ormkit.search`** — `trigram_filter(stmt, cols, q, dialect=, threshold=)`:
+  fuzzy-поиск (PostgreSQL `word_similarity`/pg_trgm с exact-boost, ILIKE-fallback
+  для остальных диалектов); возвращает `(stmt_with_where, rank_expr)`.
+- **`ormkit.rls`** — tenant Row-Level Security (defense-in-depth): `TenantContext`,
+  ContextVar-хелперы (`set`/`reset`/`current_tenant_context`), `rls_bypass`
+  контекст-менеджер, `apply_tenant_guc` (transaction-local GUC `app.rls_enforce`/
+  `app.rls_bypass`/`app.current_company`; no-op на не-PostgreSQL и при `ctx=None`).
+
+Все три модуля вынесены из skills-hub (generic SQLAlchemy, 0 завязок на приложение).
+
+## [0.0.1] - 2026-07-04
+
+### Added
+
+- **Declarative-база и миксины** (`Base`, `IntPkMixin`, `TimestampMixin`): общий
+  SQLAlchemy 2.0 declarative base и переиспользуемые миксины (int-PK, диалект-нейтральные
+  временные метки через `func.now()`)
+- **Движок из DB-URL** (`make_engine`, `make_session_factory`, `init_schema`, `drop_schema`,
+  `dispose_engine`): резолв URL (аргумент → env `ORMKIT_DB_URL` → default), ленивое
+  создание движка (postgres-URL без коннекта), автоматический `PRAGMA foreign_keys=ON` для
+  sqlite
+- **Repository-паттерн** (`BaseRepository[TModel, TDomain]`): generic CRUD
+  (`add / get / get_or_none / list / update / remove / count`) с маппингом ORM <-> domain
+  через переопределяемые хуки `to_domain` / `to_orm`
+- **Транзакционная граница** (`UnitOfWork`): контекст-менеджер с rollback при исключении,
+  гарантированным `close` и явным `commit`
+- **DIP-контракты** (`RepositoryProtocol`, `UnitOfWorkProtocol`): Protocol'ы для зависимости
+  прикладного слоя от абстракций, а не от `BaseRepository` / SQLAlchemy
+- **Исключения** (`OrmKitError`, `NotFoundError`)
+- **Тесты** (unit + integration, coverage ≥ 80%): резолв DB-URL, FK enforcement на sqlite,
+  round-trip CRUD, транзакции UoW, диалект-нейтральность временных меток; демо-модели
+  объявлены в самих тестах
+
+### Notes
+
+- Первый релиз кита `s-ormkit` как generic БД/ORM-инфраструктуры для экосистемы S-kits
+- 0 завязок на конкретное приложение: только чистая инфраструктура
+- Зависит ТОЛЬКО от SQLAlchemy>=2.0
+- Диалект-нейтрально: движок заменяется через DB-URL (sqlite → postgres → mysql) без правок кода

{s_ormkit-0.0.1 → s_ormkit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: s-ormkit
-Version: 0.0.1
+Version: 0.2.1
 Summary: Generic БД/ORM-инфраструктура на SQLAlchemy 2.0: диалект-нейтральный движок из DB-URL, Repository + UnitOfWork + DIP-протоколы. 0 завязок на конкретное приложение.
 Author: Dmitry
 License: MIT
@@ -8,10 +8,15 @@ License-File: LICENSE
 Requires-Python: >=3.11
 Requires-Dist: sqlalchemy>=2.0
 Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20; extra == 'dev'
+Requires-Dist: alembic>=1.13; extra == 'dev'
+Requires-Dist: asyncpg>=0.29; extra == 'dev'
 Requires-Dist: psycopg[binary]>=3.1; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest-cov>=6.0; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: migrations
+Requires-Dist: alembic>=1.13; extra == 'migrations'
 Description-Content-Type: text/markdown
 
 # s-ormkit
@@ -19,9 +24,9 @@ Description-Content-Type: text/markdown
 Generic БД/ORM-инфраструктура для экосистемы S-kits на SQLAlchemy 2.0: диалект-нейтральный
 движок из DB-URL, Repository + UnitOfWork + DIP-протоколы.
 
-**Версия:** 0.0.1 (первый релиз)  
+**Версия:** 0.2.0  
 **Лицензия:** MIT  
-**Зависимости:** `SQLAlchemy>=2.0` (и ничего больше)
+**Зависимости:** `SQLAlchemy>=2.0` (alembic — опционально: `s-ormkit[migrations]`)
 
 Кит НЕ знает ни о каком приложении. Прикладная логика получает БД-слой через ORM так,
 что не зависит от sqlite/диалекта: движок конфигурируется через DB-URL и заменяется на
@@ -53,6 +58,30 @@ Generic БД/ORM-инфраструктура для экосистемы S-kits
 ### DIP-контракты (`protocols.py`)
 - `RepositoryProtocol` / `UnitOfWorkProtocol` — чтобы сервисы зависели от абстракций,
   а не от `BaseRepository` / SQLAlchemy
+- `AsyncRepositoryProtocol` / `AsyncUnitOfWorkProtocol` — то же для async-слоя
+
+### Async-слой (`async_engine.py`, `async_repository.py`, `async_unit_of_work.py`)
+- `make_async_engine` / `make_async_session_factory` — асинхронный движок и
+  `async_sessionmaker(expire_on_commit=False)`; для sqlite так же включается
+  `PRAGMA foreign_keys=ON`, `create_async_engine` так же ленив
+- `init_schema_async` / `drop_schema_async` / `dispose_engine_async`
+- `AsyncUnitOfWork` / `AsyncBaseRepository` — асинхронные близнецы с ТЕМ ЖЕ API
+
+### Резолв DB-URL (`url.py`)
+- `resolve_db_url` — аргумент → переменная окружения → default (общий для sync, async
+  и миграций)
+- `async_driver_url` / `sync_driver_url` — автоподстановка драйвера
+  (`postgresql://` → `postgresql+asyncpg://` или `postgresql+psycopg://`)
+
+### Защита от N+1 (`loading.py`)
+- `LoadSpec(selectin=, joined=)` + `apply_load_spec` — декларация связей, которые
+  грузятся вместе с сущностью (в т.ч. вложенные пути `"posts.comments"`)
+- `strict_loading` / `enable_strict_loading` / `make_strict_async_session_factory` —
+  строгий режим `raiseload("*")`: незадекларированная ленивая подгрузка падает
+
+### Миграции (`migrations.py`, extra `[migrations]`)
+- `scaffold_alembic` и CLI `python -m ormkit migrations init` — генерация рабочего
+  alembic-окружения на async-движке кита
 
 ## Быстрый старт
 
@@ -134,17 +163,96 @@ def register_user(repo: RepositoryProtocol[UserDTO], name: str) -> UserDTO:
 # в проде — UserRepository, в тестах — in-memory фейк, реализующий тот же протокол
 ```
 
+### Асинхронное приложение
+
+Тот же код, но на `async/await` — форма вызова другая, структура та же:
+
+```python
+from ormkit import (
+    AsyncBaseRepository, AsyncUnitOfWork,
+    init_schema_async, make_async_engine, make_async_session_factory,
+)
+
+
+class UserRepository(AsyncBaseRepository[User, UserDTO]):
+    def to_domain(self, obj: User) -> UserDTO:
+        return UserDTO(id=obj.id, name=obj.name)
+
+    def to_orm(self, domain: UserDTO) -> User:
+        return User(name=domain.name)
+
+
+# sqlite:// → sqlite+aiosqlite://, postgresql:// → postgresql+asyncpg:// (автоматически)
+engine = make_async_engine("postgresql://user:pass@host/db")
+await init_schema_async(engine)          # в проде схему катает alembic, см. ниже
+session_factory = make_async_session_factory(engine)
+
+async with AsyncUnitOfWork(session_factory) as uow:
+    repo = UserRepository(uow.session, User)
+    saved = await repo.add(UserDTO(name="Алиса"))
+    await uow.commit()
+```
+
+### Миграции (alembic)
+
+`create_all` годится до первого изменения схемы на живых данных — дальше нужны миграции:
+
+```bash
+pip install "s-ormkit[migrations]"
+python -m ormkit migrations init . --metadata myapp.models:Base
+# дальше — штатный alembic, URL берётся из ORMKIT_DB_URL (как и у движка приложения):
+alembic revision --autogenerate -m "init"
+alembic upgrade head
+```
+
+Сгенерированный `env.py` работает на async-движке кита и с `render_as_batch=True`
+(без него sqlite не переживает ALTER). Ссылка на metadata (`pkg.module:attr`) —
+единственное, что нужно указать.
+
+### Защита от N+1
+
+Репозиторий ДЕКЛАРИРУЕТ, что грузится вместе с сущностью, а строгий режим
+не даёт незаметно уехать в ленивую подгрузку:
+
+```python
+from ormkit import LoadSpec, enable_strict_loading, make_strict_async_session_factory
+
+
+class UserRepository(AsyncBaseRepository[User, UserDTO]):
+    load_spec = LoadSpec(selectin=("posts.comments",), joined=("profile",))
+    ...
+
+
+# в conftest тестов / в CI: любая НЕобъявленная ленивая подгрузка → InvalidRequestError
+session_factory = make_strict_async_session_factory(engine)
+# либо точечно на уже открытой сессии (возвращает выключатель):
+disable = enable_strict_loading(session)
+```
+
+`selectin` — для коллекций (отдельный IN-запрос), `joined` — для «многие-к-одному»
+(один JOIN). N+1 падает на этапе тестов, а не в проде.
+
 ## Архитектура
 
 ```
 ormkit/
 ├── __init__.py          # Public API + __version__
+├── __main__.py          # CLI: python -m ormkit migrations init
 ├── exceptions.py        # OrmKitError, NotFoundError
 ├── base.py              # Base, IntPkMixin, TimestampMixin
+├── url.py               # resolve_db_url, async_driver_url, sync_driver_url
 ├── engine.py            # make_engine, make_session_factory, init/drop_schema, dispose
+├── async_engine.py      # make_async_engine, make_async_session_factory, *_async
 ├── repository.py        # BaseRepository[TModel, TDomain]
+├── async_repository.py  # AsyncBaseRepository[TModel, TDomain]
 ├── unit_of_work.py      # UnitOfWork
-└── protocols.py         # RepositoryProtocol, UnitOfWorkProtocol
+├── async_unit_of_work.py# AsyncUnitOfWork
+├── loading.py           # LoadSpec, apply_load_spec, строгий режим (raiseload)
+├── migrations.py        # scaffold_alembic, migration_url, require_alembic
+├── pagination.py        # Page, page_to_offset, paginate_stmt
+├── search.py            # trigram_filter
+├── rls.py               # TenantContext, apply_tenant_guc, rls_bypass
+└── protocols.py         # RepositoryProtocol, UnitOfWorkProtocol (+ async)
 ```
 
 ## Тестирование
@@ -167,7 +275,9 @@ uv run ruff check .       # чисто
 - **Временные метки.** `TimestampMixin` использует `func.now()`, работающий и в sqlite,
   и в postgres/mysql.
 - **Ленивое создание.** `make_engine("postgresql://...")` не коннектится — движок создаётся
-  без живого сервера.
+  без живого сервера. То же верно для `make_async_engine`.
+- **Драйвер подставляется сам.** `postgresql://` становится `postgresql+asyncpg://` в
+  async-контексте и `postgresql+psycopg://` в синхронном; явно заданный драйвер не трогается.
 
 ## Лицензия
 

{s_ormkit-0.0.1 → s_ormkit-0.2.1}/README.md

@@ -3,9 +3,9 @@
 Generic БД/ORM-инфраструктура для экосистемы S-kits на SQLAlchemy 2.0: диалект-нейтральный
 движок из DB-URL, Repository + UnitOfWork + DIP-протоколы.
 
-**Версия:** 0.0.1 (первый релиз)  
+**Версия:** 0.2.0  
 **Лицензия:** MIT  
-**Зависимости:** `SQLAlchemy>=2.0` (и ничего больше)
+**Зависимости:** `SQLAlchemy>=2.0` (alembic — опционально: `s-ormkit[migrations]`)
 
 Кит НЕ знает ни о каком приложении. Прикладная логика получает БД-слой через ORM так,
 что не зависит от sqlite/диалекта: движок конфигурируется через DB-URL и заменяется на
@@ -37,6 +37,30 @@ Generic БД/ORM-инфраструктура для экосистемы S-kits
 ### DIP-контракты (`protocols.py`)
 - `RepositoryProtocol` / `UnitOfWorkProtocol` — чтобы сервисы зависели от абстракций,
   а не от `BaseRepository` / SQLAlchemy
+- `AsyncRepositoryProtocol` / `AsyncUnitOfWorkProtocol` — то же для async-слоя
+
+### Async-слой (`async_engine.py`, `async_repository.py`, `async_unit_of_work.py`)
+- `make_async_engine` / `make_async_session_factory` — асинхронный движок и
+  `async_sessionmaker(expire_on_commit=False)`; для sqlite так же включается
+  `PRAGMA foreign_keys=ON`, `create_async_engine` так же ленив
+- `init_schema_async` / `drop_schema_async` / `dispose_engine_async`
+- `AsyncUnitOfWork` / `AsyncBaseRepository` — асинхронные близнецы с ТЕМ ЖЕ API
+
+### Резолв DB-URL (`url.py`)
+- `resolve_db_url` — аргумент → переменная окружения → default (общий для sync, async
+  и миграций)
+- `async_driver_url` / `sync_driver_url` — автоподстановка драйвера
+  (`postgresql://` → `postgresql+asyncpg://` или `postgresql+psycopg://`)
+
+### Защита от N+1 (`loading.py`)
+- `LoadSpec(selectin=, joined=)` + `apply_load_spec` — декларация связей, которые
+  грузятся вместе с сущностью (в т.ч. вложенные пути `"posts.comments"`)
+- `strict_loading` / `enable_strict_loading` / `make_strict_async_session_factory` —
+  строгий режим `raiseload("*")`: незадекларированная ленивая подгрузка падает
+
+### Миграции (`migrations.py`, extra `[migrations]`)
+- `scaffold_alembic` и CLI `python -m ormkit migrations init` — генерация рабочего
+  alembic-окружения на async-движке кита
 
 ## Быстрый старт
 
@@ -118,17 +142,96 @@ def register_user(repo: RepositoryProtocol[UserDTO], name: str) -> UserDTO:
 # в проде — UserRepository, в тестах — in-memory фейк, реализующий тот же протокол
 ```
 
+### Асинхронное приложение
+
+Тот же код, но на `async/await` — форма вызова другая, структура та же:
+
+```python
+from ormkit import (
+    AsyncBaseRepository, AsyncUnitOfWork,
+    init_schema_async, make_async_engine, make_async_session_factory,
+)
+
+
+class UserRepository(AsyncBaseRepository[User, UserDTO]):
+    def to_domain(self, obj: User) -> UserDTO:
+        return UserDTO(id=obj.id, name=obj.name)
+
+    def to_orm(self, domain: UserDTO) -> User:
+        return User(name=domain.name)
+
+
+# sqlite:// → sqlite+aiosqlite://, postgresql:// → postgresql+asyncpg:// (автоматически)
+engine = make_async_engine("postgresql://user:pass@host/db")
+await init_schema_async(engine)          # в проде схему катает alembic, см. ниже
+session_factory = make_async_session_factory(engine)
+
+async with AsyncUnitOfWork(session_factory) as uow:
+    repo = UserRepository(uow.session, User)
+    saved = await repo.add(UserDTO(name="Алиса"))
+    await uow.commit()
+```
+
+### Миграции (alembic)
+
+`create_all` годится до первого изменения схемы на живых данных — дальше нужны миграции:
+
+```bash
+pip install "s-ormkit[migrations]"
+python -m ormkit migrations init . --metadata myapp.models:Base
+# дальше — штатный alembic, URL берётся из ORMKIT_DB_URL (как и у движка приложения):
+alembic revision --autogenerate -m "init"
+alembic upgrade head
+```
+
+Сгенерированный `env.py` работает на async-движке кита и с `render_as_batch=True`
+(без него sqlite не переживает ALTER). Ссылка на metadata (`pkg.module:attr`) —
+единственное, что нужно указать.
+
+### Защита от N+1
+
+Репозиторий ДЕКЛАРИРУЕТ, что грузится вместе с сущностью, а строгий режим
+не даёт незаметно уехать в ленивую подгрузку:
+
+```python
+from ormkit import LoadSpec, enable_strict_loading, make_strict_async_session_factory
+
+
+class UserRepository(AsyncBaseRepository[User, UserDTO]):
+    load_spec = LoadSpec(selectin=("posts.comments",), joined=("profile",))
+    ...
+
+
+# в conftest тестов / в CI: любая НЕобъявленная ленивая подгрузка → InvalidRequestError
+session_factory = make_strict_async_session_factory(engine)
+# либо точечно на уже открытой сессии (возвращает выключатель):
+disable = enable_strict_loading(session)
+```
+
+`selectin` — для коллекций (отдельный IN-запрос), `joined` — для «многие-к-одному»
+(один JOIN). N+1 падает на этапе тестов, а не в проде.
+
 ## Архитектура
 
 ```
 ormkit/
 ├── __init__.py          # Public API + __version__
+├── __main__.py          # CLI: python -m ormkit migrations init
 ├── exceptions.py        # OrmKitError, NotFoundError
 ├── base.py              # Base, IntPkMixin, TimestampMixin
+├── url.py               # resolve_db_url, async_driver_url, sync_driver_url
 ├── engine.py            # make_engine, make_session_factory, init/drop_schema, dispose
+├── async_engine.py      # make_async_engine, make_async_session_factory, *_async
 ├── repository.py        # BaseRepository[TModel, TDomain]
+├── async_repository.py  # AsyncBaseRepository[TModel, TDomain]
 ├── unit_of_work.py      # UnitOfWork
-└── protocols.py         # RepositoryProtocol, UnitOfWorkProtocol
+├── async_unit_of_work.py# AsyncUnitOfWork
+├── loading.py           # LoadSpec, apply_load_spec, строгий режим (raiseload)
+├── migrations.py        # scaffold_alembic, migration_url, require_alembic
+├── pagination.py        # Page, page_to_offset, paginate_stmt
+├── search.py            # trigram_filter
+├── rls.py               # TenantContext, apply_tenant_guc, rls_bypass
+└── protocols.py         # RepositoryProtocol, UnitOfWorkProtocol (+ async)
 ```
 
 ## Тестирование
@@ -151,7 +254,9 @@ uv run ruff check .       # чисто
 - **Временные метки.** `TimestampMixin` использует `func.now()`, работающий и в sqlite,
   и в postgres/mysql.
 - **Ленивое создание.** `make_engine("postgresql://...")` не коннектится — движок создаётся
-  без живого сервера.
+  без живого сервера. То же верно для `make_async_engine`.
+- **Драйвер подставляется сам.** `postgresql://` становится `postgresql+asyncpg://` в
+  async-контексте и `postgresql+psycopg://` в синхронном; явно заданный драйвер не трогается.
 
 ## Лицензия
 

s_ormkit-0.2.1/docs/adr/0000-template.md

@@ -0,0 +1,20 @@
+# NNNN. Краткий заголовок решения
+
+- **Статус:** proposed | accepted | superseded (→ ADR-NNNN) | deprecated
+- **Дата:** ГГГГ-ММ-ДД
+
+## Контекст
+
+Какую ситуацию/проблему решаем. Что вынуждает принять решение сейчас: ограничения, требования, силы, которые тянут в разные стороны. Достаточно, чтобы понять «почему» без внешнего контекста.
+
+## Решение
+
+Что именно решили — одной-двумя фразами, в настоящем времени: «Делаем X». Конкретно и проверяемо.
+
+## Последствия
+
+Что становится проще и что — сложнее/дороже после принятия. Плюсы, минусы, новые обязательства и ограничения, которые теперь придётся держать.
+
+## Альтернативы
+
+Какие варианты рассматривали и **почему отклонили** (в этом ценность записи). Кратко: вариант → причина отказа / отложено до условия.

s_ormkit-0.2.1/docs/adr/README.md

@@ -0,0 +1,30 @@
+# ADR — журнал архитектурных решений
+
+**Что это.** ADR (Architecture Decision Record) — короткий документ на **одно** архитектурное решение: контекст → что решили → почему → последствия. Лежат здесь, в `docs/adr/`, со **сквозной нумерацией** (`0001-…`, `0002-…`). Шаблон — [`0000-template.md`](0000-template.md).
+
+**Зачем.** «Почему» проекта нельзя держать в комментариях к задачам и переписке — оно теряется. ADR — дистиллят решения: агент читает его **перед** правкой и не «чинит» то, что было выбрано сознательно. Дёшев по токенам: одно решение прочитать проще, чем реконструировать его из истории коммитов.
+
+## Когда заводить ADR — когда сошлись 3 условия
+
+1. решение **дорого откатить** (влияет на структуру, данные, контракты);
+2. без контекста оно **выглядит странно** (кто-то потом захочет «починить»);
+3. были **реальные альтернативы** и выбор — осознанный трейдофф.
+
+Если хотя бы одно условие не выполнено — ADR не нужен, хватит `comment` на задаче в Atlas.
+
+## Правила ведения
+
+- **Нумерация сквозная**, файл — `NNNN-краткий-слаг.md` (`0001-operating-model-foundamentals.md`).
+- **Не редактировать задним числом.** Принятое решение — исторический факт. Если решение отменено новым — старому ставим `Статус: superseded` (со ссылкой на новое ADR), а не переписываем его.
+- **«Схлопывание».** Когда цепочка `superseded` разрослась, допустимо свести её к одному ADR с текущим состоянием — ради экономии контекста агента. Прежние помечаем как схлопнутые.
+- **Статусы:** `proposed` → `accepted` → (`superseded` / `deprecated`).
+
+## Что НЕ идёт в ADR
+
+- **состояние** (ветка/worktree, стадия) — это тег/поле задачи в Atlas;
+- **ход работы / handoff** — `comment` на задаче в Atlas;
+- **черновой план реализации** — scratchpad, в `.gitignore`, в репо не коммитится.
+
+Полная модель фиксации артефактов (4 слоя) — в `ai-ecosystem-core/AGENT-OPERATING-MODEL.md`, раздел «Модель фиксации артефактов».
+
+**Методология:** практика ADR (Michael Nygard), компактный формат Matt Pocock (`github.com/mattpocock/skills`, grill-with-docs), примеры в NATS / AG2.