s-corekit 0.0.2__tar.gz → 0.0.4__tar.gz

{s_corekit-0.0.2 → s_corekit-0.0.4}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # CHANGELOG — s-corekit
 
+## [0.0.3] — 2026-08-08
+
+### Добавлено
+
+- `SessionRef` получил две координаты: `instance` — конкретный вход
+  многоинстансного сервиса (портал Битрикса, национальный домен), `stage` —
+  стадия сессии (боевая или черновик записи трафика). Обе добавлены В КОНЕЦ и
+  с дефолтами, как когда-то `tenant`: позиционный
+  `SessionRef(profile, social, account_id)` из чужих навыков и уже записанные
+  адреса продолжают работать.
+- `DEFAULT_STAGE` — стадия боевой сессии (`"live"`), дефолт адреса.
+
+Зачем. Стадия до сих пор занимала поле `profile`, и два смысла в одном поле
+означали адрес, по которому нельзя спросить «дай боевую сессию ЭТОГО
+аккаунта», не зная заранее, как её назвал пишущий. Порталы одного продукта
+разводились ВТОРЫМ именем сервиса — от этого у аккаунта появлялась вторая
+сессия, о которой никто не знал.
+
 ## [0.0.2] — 2026-08-04
 
 ### Fixed

{s_corekit-0.0.2 → s_corekit-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s-corekit
-Version: 0.0.2
+Version: 0.0.4
 Summary: ОСНОВАНИЕ китов: ExecutionContext, базовые DTO (SessionRef/Creds/LimitSpec/QuotaInfo), единая иерархия ошибок и чистая классификация состояния доступа (AccessState/AccessVerdict). Только stdlib.
 Author: Dmitry
 License: MIT

{s_corekit-0.0.2 → s_corekit-0.0.4}/corekit/__init__.py

@@ -45,7 +45,7 @@
 """
 from __future__ import annotations
 
-from corekit.context import DEFAULT_TENANT, ExecutionContext
+from corekit.context import DEFAULT_STAGE, DEFAULT_TENANT, ExecutionContext
 from corekit.diagnosis import (
     ACCESS_STATE_MESSAGES,
     REASON_MESSAGES,
@@ -99,12 +99,13 @@ from corekit.redaction import (
     truncate_body,
 )
 
-__version__ = "0.0.2"
+__version__ = "0.0.4"
 
 __all__ = [
     "__version__",
     # контекст исполнения
     "ExecutionContext",
+    "DEFAULT_STAGE",
     "DEFAULT_TENANT",
     # базовые DTO
     "SessionRef",

{s_corekit-0.0.2 → s_corekit-0.0.4}/corekit/context.py

@@ -17,6 +17,7 @@ from pathlib import Path
 from typing import Any
 
 __all__ = [
+    "DEFAULT_STAGE",
     "DEFAULT_TENANT",
     "ExecutionContext",
 ]
@@ -26,6 +27,16 @@ __all__ = [
 #: байт-в-байт совпадают с тем, что было до введения мультитенантности.
 DEFAULT_TENANT = "local"
 
+#: Стадия БОЕВОЙ сессии — той, которой работают. Дефолт `SessionRef`: пока
+#: стадию не назвали явно, адрес совпадает с досегодняшним, и все уже
+#: записанные сессии читаются как боевые (чем они и были).
+#:
+#: Вторая стадия — черновик записи трафика (`capture`): вход туда может не
+#: удаться (в окне осталась форма), и такой снимок не должен затирать рабочую
+#: сессию. Стадий ровно две по замыслу: третья означала бы, что мы моделируем
+#: здесь жизненный цикл, а не разводим «проверено» и «ещё нет».
+DEFAULT_STAGE = "live"
+
 
 #: Сентинел «аргумент не передан» для `ExecutionContext.__init__`: отличает
 #: «поле оставили по умолчанию» от «поле передали, и значение совпало с дефолтом».

{s_corekit-0.0.2 → s_corekit-0.0.4}/corekit/diagnosis/access.py

@@ -131,6 +131,14 @@ LOGIN_HOST_MARKERS: tuple[str, ...] = (
     "/login?continue=",
     "/oauth/authorize",
     "/auth/login",
+    # Ниже — из браузерного кита, где годами жила ВТОРАЯ таблица тех же улик.
+    # Копии расходятся молча: одна узнавала увод на вход, другая нет, и вердикт
+    # зависел от того, каким путём пошёл вызывающий.
+    "/login",
+    "/signin",
+    "/auth/",
+    "passport.",   # внешний провайдер входа (Яндекс и подобные)
+    "pincode",     # экран второго фактора — вход ещё не завершён
 )
 
 #: Тело-улики «сервер не знает сессию». Именно ПРЕДЪЯВЛЕННЫЕ и отвергнутые куки,
@@ -169,6 +177,12 @@ TOKEN_EXPIRED_MARKERS: tuple[str, ...] = (
     "unauthenticated",
     "invalid authentication credentials",
     "csrf token",
+    "csrf-token",
+    "invalid-csrf",
+    # Замаскированное протухание csrf: сервис отвечает «неверный параметр»,
+    # не называя причину. Улика попала сюда из браузерного кита — там она
+    # была снята живьём и служила ровно этому диагнозу.
+    "illegalparameterexception",
     "xsrf",
     "sapisidhash",
     "invalid at token",

s_corekit-0.0.4/corekit/dto.py

@@ -0,0 +1,149 @@
+"""Базовые DTO-ЗНАЧЕНИЯ основания: координаты сессии, креды, тело RPC-запроса.
+
+Критерий, по которому DTO попал сюда, ровно один: он НЕ ТЯНЕТ РЕАЛИЗАЦИЮ. Это
+неизменяемые значения (`frozen=True, slots=True`) — их можно шарить между
+потоками, класть в ключи, логировать (кроме `Creds`) и сериализовать
+``dataclasses.asdict``. Всё, что имеет жизненный цикл (клиенты, сторы,
+браузеры), остаётся слоями выше.
+
+ТОЛЬКО stdlib. Перенесено из ``librarykit.contract`` БЕЗ
+изменения формы: порядок полей и дефолты те же, поэтому позиционные вызовы и
+уже записанные данные продолжают работать.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from corekit.context import DEFAULT_STAGE, DEFAULT_TENANT
+
+__all__ = [
+    "Creds",
+    "RequestBody",
+    "SessionRef",
+    "cookies_from_storage_state",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class SessionRef:
+    """Координаты сессии в `SessionStore`: profile / social / account-id.
+
+    Тройка ``profile``/``social``/``account_id`` однозначно адресует каталог
+    сессии ``<profile>/<social>/<account_id>/`` под корнем sessions. Без секретов —
+    это только ключ/путь, поэтому безопасно логировать и индексировать.
+
+    ``tenant`` — ЧЕТВЁРТАЯ (последняя, с дефолтом) координата: владелец сессии в
+    мультитенантном хосте. Поле добавлено В КОНЕЦ, поэтому позиционное
+    ``SessionRef(profile, social, account_id)`` и сравнение старых объектов
+    продолжают работать.
+
+    Координата ПОДКЛЮЧЕНА: при ``tenant != DEFAULT_TENANT`` каталог сессии
+    получает ведущий сегмент — ``<tenant>/<profile>/<social>/<account_id>/``, а
+    первичный ключ индекса — ``(tenant, profile, social, account_id)``. При
+    дефолтном ``"local"`` раскладка и ключ байт-в-байт прежние (сегмент не
+    добавляется), поэтому существующие сессии читаются как раньше. Пересборка
+    индекса из каталога — `SessionStore.reindex` (понимает обе глубины).
+
+    ``instance`` — КОНКРЕТНЫЙ вход сервиса, у которого их много: портал
+    Битрикса (``acme.bitrix24.ru``), национальный домен, отдельная установка.
+    Продукт при этом один, и разводить такие входы вторым ИМЕНЕМ сервиса
+    (``bitrix24-kz``) нельзя: имена размножаются, а у одного аккаунта появляется
+    вторая сессия, о которой никто не знает. Пусто — у сервиса один вход, и
+    адрес совпадает с прежним.
+
+    ``stage`` — стадия сессии: боевая (:data:`~corekit.context.DEFAULT_STAGE`)
+    или черновик записи трафика (``capture``). Стадия обязана быть ОТДЕЛЬНОЙ
+    координатой, а не значением ``profile``: профиль отвечает на вопрос «чей
+    это вход», стадия — «проверен ли он». Совмещая два смысла в одном поле,
+    получаешь адрес, по которому нельзя спросить «дай боевую сессию ЭТОГО
+    аккаунта», не зная заранее, как её назвал пишущий.
+
+    Обе координаты добавлены В КОНЕЦ и с дефолтами — по той же причине, что и
+    ``tenant``: позиционные вызовы, сравнение старых объектов и уже записанные
+    адреса продолжают работать.
+    """
+
+    profile: str
+    social: str
+    account_id: str
+    tenant: str = DEFAULT_TENANT
+    instance: str = ""
+    stage: str = DEFAULT_STAGE
+
+
+@dataclass(frozen=True, slots=True)
+class RequestBody:
+    """Тело RPC-запроса после `Codec.encode_request` (E1.T2): json XOR data.
+
+    Нейтральный носитель сериализованного payload между codec и транспортом:
+    `json` уходит в `Transport.request(json=...)` (httpx сам сериализует), а
+    `data` — сырое тело (bytes/str/form) для не-JSON envelope. Заполняется ровно
+    одно из двух; `headers` опц. добавляет codec-специфичные заголовки
+    (`Content-Type` и т.п.) к запросу.
+    """
+
+    json: Any | None = None
+    data: Any | None = None
+    headers: Mapping[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class Creds:
+    """Секреты авторизации одной сессии (НЕ логировать, НЕ сериализовать в индекс).
+
+    Гибкий контейнер под разные `AuthMode`: токены (token-auth), refresh-токен
+    (oauth2), cookies (cookie-сессия), произвольные `extra` (например, подписи).
+    Все поля опциональны — заполняется то, что нужно конкретному режиму.
+    """
+
+    token: str | None = None
+    refresh_token: str | None = None
+    cookies: Mapping[str, str] = field(default_factory=dict)
+    extra: Mapping[str, Any] = field(default_factory=dict)
+
+
+def cookies_from_storage_state(
+    state: object,
+    *,
+    domain_substr: str = "",
+) -> dict[str, str]:
+    """``storage_state`` → плоский ``{имя: значение}``, как хочет HTTP-клиент.
+
+    ОДИН РАЗБОР НА ВСЕ КИТЫ. Одно и то же преобразование жило копиями: одна
+    читала файл и умела фильтр по домену, другая работала со словарём и знала
+    про плоскую форму. Копии расходятся молча, а цена расхождения здесь
+    несимметрична — лишняя кука уезжает чужому сервису, недостающая ломает
+    сессию.
+
+    Принимает обе формы, потому что обе живут в системе:
+
+    * Playwright: ``{"cookies": [{"name", "value", "domain", …}]}``;
+    * плоскую: ``{имя: значение}`` (так их хранят креды).
+
+    ``domain_substr`` отсекает куки сторонних доменов — их отправка боевому API
+    и есть тот запрос, который сервис вправе счесть подозрительным.
+
+    Здесь, в основании, потому что это чистая работа со структурой: ни сети, ни
+    диска, ни знания о сервисе. Кто и где хранит снимок — вопрос сессионного
+    слоя, а не этого разбора.
+    """
+    if not isinstance(state, Mapping):
+        return {}
+    raw = state.get("cookies")
+    if isinstance(raw, list):
+        out: dict[str, str] = {}
+        for item in raw:
+            if not isinstance(item, Mapping):
+                continue
+            if domain_substr and domain_substr not in str(item.get("domain") or ""):
+                continue
+            name, value = item.get("name"), item.get("value")
+            if name is not None and value is not None:
+                out[str(name)] = str(value)
+        return out
+    # Плоская форма домена не несёт, поэтому фильтровать по нему нечем: молча
+    # вернуть пусто значило бы «сессии нет» там, где она есть.
+    flat = raw if isinstance(raw, Mapping) else state
+    return {str(k): str(v) for k, v in flat.items() if k != "origins"}

s_corekit-0.0.4/corekit/filelock.py

@@ -0,0 +1,165 @@
+"""Межпроцессный advisory-лок на файле: одна механика на все киты.
+
+ЗАЧЕМ ЭТОТ МОДУЛЬ. Одна и та же вещь была написана трижды — в сессионном ките
+(`SessionFileLock`), в пуле аккаунтов (`_AccountLock`) и там же ещё раз под
+строковый ключ (`KeyedProcessLock`, чей докстринг прямо называет себя портом
+второго). Три копии критической секции — это три разных ответа на вопрос «что
+делать с осиротевшим локом»: процесс упал, файл остался, и дальше поведение
+зависит от того, чей код первым дошёл до записи. Для сессии цена такой разницы —
+затёртая чужая ротация кук, то есть потерянный вход.
+
+ПОЧЕМУ В ОСНОВАНИИ. Здесь нет ни сети, ни домена, ни знания о сессиях: только
+файл, часы и stdlib. Кит с нулевыми зависимостями — единственное место, куда
+могут смотреть все три прежних владельца, не создавая обратных связей.
+
+ЧЕГО ЗДЕСЬ НЕТ. Реентерабельности (её отсутствие намеренно: рекурсивный захват
+скрывает ошибку владения) и очереди справедливости — ожидание опросом, потому
+что критические секции здесь короткие, а зависимостей ради «правильной» очереди
+кит заводить не станет.
+"""
+from __future__ import annotations
+
+import contextlib
+import os
+import time
+from pathlib import Path
+
+__all__ = ["FileLock", "LockTimeout"]
+
+
+class LockTimeout(TimeoutError):  # noqa: N818 — подтип TimeoutError, доменное имя
+    """Лок не взят за отведённое время: его держит другой писатель."""
+
+
+class FileLock:
+    """Эксклюзивный лок через атомарное создание файла (``O_CREAT|O_EXCL``).
+
+    Атомарность создания даёт и POSIX, и Windows — поэтому внешняя библиотека не
+    нужна. Лок держится на всё окно работы, чтобы конкурентные писатели (фоновое
+    продление, команда человека, авто-обновление) не затирали друг друга.
+
+    ``stale_after`` ломает ОСИРОТЕВШИЙ лок: процесс упал, файл остался, и без
+    этого правила система встаёт намертво до ручной уборки. Значение по
+    умолчанию заведомо больше любой честной критической секции — лучше подождать
+    лишнее, чем забрать лок у живого писателя.
+
+    Не реентерабелен: повторный захват тем же владельцем — это почти всегда
+    потерянный ``release`` в чужой ветке, и молча его прощать значит однажды
+    отпустить лок дважды.
+    """
+
+    def __init__(
+        self,
+        path: str | os.PathLike[str],
+        *,
+        timeout: float = 30.0,
+        poll: float = 0.05,
+        stale_after: float | None = 900.0,
+        clock: object | None = None,
+    ) -> None:
+        self._path = Path(path)
+        self._timeout = timeout
+        self._poll = poll
+        self._stale_after = stale_after
+        #: Источник настенного времени. Инъекция нужна не ради красоты: тест на
+        #: перехват осиротевшего лока иначе идёт столько же, сколько порог, —
+        #: то есть его не пишут вовсе, и правило остаётся непроверенным.
+        self._clock = clock or time.time
+        self._fd: int | None = None
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    @property
+    def locked(self) -> bool:
+        return self._fd is not None
+
+    def _try_acquire(self) -> bool:
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            fd = os.open(self._path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            return False
+        # Кто держит и с какого момента — это читают люди, разбирая зависший
+        # лок. Без записи остаётся пустой файл, по которому не сказать ничего.
+        os.write(fd, f"{os.getpid()}\n{time.time()}".encode())
+        self._fd = fd
+        return True
+
+    def _break_if_stale(self) -> None:
+        if self._stale_after is None:
+            return
+        try:
+            age = self._clock() - self._path.stat().st_mtime
+        except OSError:
+            return
+        if age > self._stale_after:
+            with contextlib.suppress(OSError):
+                self._path.unlink()
+
+    def acquire(self, *, raising: bool = True) -> bool:
+        """Взять лок (блокирующе, опросом). Возвращает, взят ли он.
+
+        ДВА ЧЕСТНЫХ ОТВЕТА НА ЗАНЯТЫЙ ЛОК, и выбор за вызывающим:
+
+        * ``raising=True`` — ``LockTimeout``. Так ведёт себя тот, для кого
+          войти в секцию обязательно: писатель сессии, затерев чужую ротацию,
+          отбирает у человека вход.
+        * ``raising=False`` — ``False`` без исключения. Так ведёт себя тот, кому
+          важнее не встать намертво: пул аккаунтов уже держит внутрипроцессный
+          лок, и одна возможная гонка между процессами для него дешевле вечной
+          блокировки.
+
+        Разные ответы — не небрежность, а разная цена ошибки; поэтому они
+        названы явно, а не разъехались двумя копиями кода.
+        """
+        if self._fd is not None:
+            return True
+        deadline = time.monotonic() + self._timeout
+        while True:
+            if self._try_acquire():
+                return True
+            self._break_if_stale()
+            if time.monotonic() >= deadline:
+                if raising:
+                    raise LockTimeout(
+                        f"Лок {self._path} занят другим писателем: не взят за "
+                        f"{self._timeout:.1f}s."
+                    )
+                return False
+            time.sleep(self._poll)
+
+    def release(self) -> None:
+        """Отпустить лок. Идемпотентно: отпустить дважды — не ошибка."""
+        if self._fd is not None:
+            with contextlib.suppress(OSError):
+                os.close(self._fd)
+            self._fd = None
+        with contextlib.suppress(OSError):
+            self._path.unlink()
+
+    async def acquire_async(self, *, raising: bool = True) -> bool:
+        """Взять лок, не стопоря event loop: опрос уходит в поток."""
+        import asyncio
+
+        return await asyncio.to_thread(self.acquire, raising=raising)
+
+    async def release_async(self) -> None:
+        import asyncio
+
+        await asyncio.to_thread(self.release)
+
+    def __enter__(self) -> FileLock:
+        self.acquire()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.release()
+
+    async def __aenter__(self) -> FileLock:
+        await self.acquire_async()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.release_async()

{s_corekit-0.0.2 → s_corekit-0.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "s-corekit"
-version = "0.0.2"
+version = "0.0.4"
 description = "ОСНОВАНИЕ китов: ExecutionContext, базовые DTO (SessionRef/Creds/LimitSpec/QuotaInfo), единая иерархия ошибок и чистая классификация состояния доступа (AccessState/AccessVerdict). Только stdlib."
 readme = "README.md"
 license = { text = "MIT" }

{s_corekit-0.0.2 → s_corekit-0.0.4}/tests/test_diagnosis_access.py

@@ -130,3 +130,33 @@ def test_verdict_serializes_flat_with_its_evidence():
     assert payload["state"] == "session_dead"
     assert payload["why"] == "почему" and payload["evidence"] == "улика"
     assert payload["message"]
+
+
+# =========================================================================== #
+# Улики входа и протухания — ОДИН словарь на все киты                          #
+# =========================================================================== #
+
+
+def test_login_markers_cover_what_the_browser_kit_knew_alone():
+    """Улики увода на вход собраны в основании, а не в копии браузерного кита.
+
+    Копии расходятся молча: одна таблица узнавала внешний провайдер входа и
+    экран второго фактора, другая — хосты Google. Вердикт «сессия мертва»
+    зависел от того, каким путём пошёл вызывающий.
+    """
+    from corekit.diagnosis.access import LOGIN_HOST_MARKERS
+
+    for marker in ("accounts.google.com", "/login", "/signin", "passport.", "pincode"):
+        assert marker in LOGIN_HOST_MARKERS, f"улика входа {marker!r} потеряна при сведении"
+
+
+def test_token_markers_keep_the_masked_csrf_evidence():
+    """Замаскированное протухание csrf: сервис отвечает «неверный параметр».
+
+    Улика снята живьём в браузерном ките; при сведении таблиц её легко было
+    потерять — она не похожа ни на одно слово про токен.
+    """
+    from corekit.diagnosis.access import TOKEN_EXPIRED_MARKERS
+
+    for marker in ("csrf-token", "invalid-csrf", "illegalparameterexception"):
+        assert marker in TOKEN_EXPIRED_MARKERS, f"улика {marker!r} потеряна при сведении"

s_corekit-0.0.4/tests/test_filelock.py

@@ -0,0 +1,87 @@
+"""Файловый лок: одна механика на все киты.
+
+Раньше та же вещь была написана трижды — в сессионном ките, в пуле аккаунтов и
+там же ещё раз под строковый ключ. Три копии критической секции — это три разных
+ответа на вопрос «что делать с осиротевшим локом». Для сессии цена расхождения:
+затёртая чужая ротация кук, то есть потерянный вход.
+"""
+from __future__ import annotations
+
+import pytest
+
+from corekit.filelock import FileLock, LockTimeout
+
+
+def test_second_writer_does_not_get_the_lock(tmp_path):
+    """Двое не входят в критическую секцию одновременно — иначе она бессмысленна."""
+    path = tmp_path / "session.lock"
+    with FileLock(path):
+        with pytest.raises(LockTimeout):
+            FileLock(path, timeout=0.1, poll=0.01, stale_after=None).acquire()
+
+
+def test_lock_is_released_for_the_next_writer(tmp_path):
+    """После выхода лок свободен: иначе первый же писатель вешает систему."""
+    path = tmp_path / "session.lock"
+    with FileLock(path):
+        pass
+
+    with FileLock(path, timeout=0.5):
+        assert path.exists(), "лок взят, но файла нет — второй писатель войдёт следом"
+
+
+def test_orphaned_lock_is_broken(tmp_path):
+    """Процесс упал, файл остался — без перехвата система встаёт до ручной уборки."""
+    path = tmp_path / "session.lock"
+    path.write_text("999999\n0", encoding="utf-8")
+
+    # Возраст файла заведомо больше порога: перехват обязан сработать.
+    with FileLock(path, timeout=0.5, poll=0.01, stale_after=0.0) as lock:
+        assert lock.locked
+
+
+def test_living_writer_is_never_robbed(tmp_path):
+    """Порог перехвата не должен забирать лок у живого: он держит секцию честно."""
+    path = tmp_path / "session.lock"
+    with FileLock(path):
+        with pytest.raises(LockTimeout):
+            FileLock(path, timeout=0.1, poll=0.01, stale_after=900.0).acquire()
+
+
+def test_release_twice_is_not_an_error(tmp_path):
+    """Отпустить дважды — обычный путь при ошибке в середине работы."""
+    lock = FileLock(tmp_path / "session.lock")
+    lock.acquire()
+    lock.release()
+    lock.release()
+
+    assert not lock.locked
+
+
+def test_non_raising_mode_answers_false_instead_of_blocking(tmp_path):
+    """Пулу аккаунтов важнее не встать намертво, чем не разойтись с соседом.
+
+    Он уже держит внутрипроцессный лок, поэтому одна возможная гонка между
+    процессами для него дешевле вечной блокировки. Писателю сессии — наоборот:
+    затерев чужую ротацию, он отбирает у человека вход. Два ответа названы
+    явно, чтобы они снова не разъехались двумя копиями кода.
+    """
+    path = tmp_path / "session.lock"
+    with FileLock(path):
+        assert FileLock(path, timeout=0.1, poll=0.01, stale_after=None).acquire(
+            raising=False
+        ) is False
+
+
+def test_clock_injection_keeps_the_stale_test_short(tmp_path):
+    """Порог перехвата проверяется подменой часов, а не ожиданием в сутки.
+
+    Без инъекции такой тест идёт столько же, сколько порог, — то есть его не
+    пишут вовсе, и правило остаётся непроверенным.
+    """
+    path = tmp_path / "session.lock"
+    path.write_text("1\n0", encoding="utf-8")
+    ahead = path.stat().st_mtime + 10_000
+
+    with FileLock(path, timeout=0.5, poll=0.01, stale_after=900.0, clock=lambda: ahead) as lock:
+        assert lock.locked, "осиротевший лок не перехвачен при сдвинутых часах"

s_corekit-0.0.4/tests/test_session_ref.py

@@ -0,0 +1,65 @@
+"""Адрес сессии: две новые координаты не ломают ни одного старого вызова.
+
+Почему это проверяется отдельно. `SessionRef` — общий словарь между китами,
+навыками и хранилищем: его собирают в одном месте, а разбирают в четырёх. Любая
+правка формы здесь дороже обычной: старый позиционный вызов, лежащий в чужом
+навыке, обязан продолжить работать, а уже записанные адреса — читаться.
+"""
+from __future__ import annotations
+
+import dataclasses
+
+import pytest
+
+from corekit import DEFAULT_STAGE, DEFAULT_TENANT, SessionRef
+
+
+def test_old_positional_call_still_works() -> None:
+    """Тройка без новых координат собирается как раньше — и это боевая сессия."""
+    ref = SessionRef("default", "grok", "me")
+
+    assert (ref.profile, ref.social, ref.account_id) == ("default", "grok", "me")
+    assert ref.tenant == DEFAULT_TENANT
+    assert ref.instance == ""
+    assert ref.stage == DEFAULT_STAGE
+
+
+def test_stage_makes_two_different_addresses() -> None:
+    """Черновик и боевая — РАЗНЫЕ адреса одного аккаунта, а не один.
+
+    Ровно это и защищает рабочую сессию от неудачного захода в capture.
+    """
+    live = SessionRef("default", "grok", "me")
+    draft = SessionRef("default", "grok", "me", stage="capture")
+
+    assert live != draft
+
+
+def test_instance_separates_portals_of_one_service() -> None:
+    """Два портала одного продукта — разные адреса при одном имени сервиса."""
+    acme = SessionRef("default", "bitrix24", "me", instance="acme.bitrix24.ru")
+    beta = SessionRef("default", "bitrix24", "me", instance="beta.bitrix24.kz")
+
+    assert acme != beta
+    assert acme.social == beta.social == "bitrix24"
+
+
+def test_ref_stays_hashable_and_frozen() -> None:
+    """Адрес остаётся значением: годится в ключ и не меняется на ходу."""
+    ref = SessionRef("default", "grok", "me", stage="capture")
+
+    assert {ref: 1}[SessionRef("default", "grok", "me", stage="capture")] == 1
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        ref.stage = "live"  # type: ignore[misc]
+
+
+def test_new_fields_are_last() -> None:
+    """Новые координаты стоят В КОНЦЕ — иначе позиционные вызовы молча съедут.
+
+    Проверка не про эстетику: `SessionRef("default", "grok", "me")` живёт в
+    чужих навыках, и перестановка полей превратила бы имя сервиса в стадию,
+    не вызвав ни одной ошибки.
+    """
+    names = [f.name for f in dataclasses.fields(SessionRef)]
+
+    assert names == ["profile", "social", "account_id", "tenant", "instance", "stage"]

s_corekit-0.0.2/corekit/dto.py

@@ -1,83 +0,0 @@
-"""Базовые DTO-ЗНАЧЕНИЯ основания: координаты сессии, креды, тело RPC-запроса.
-
-Критерий, по которому DTO попал сюда, ровно один: он НЕ ТЯНЕТ РЕАЛИЗАЦИЮ. Это
-неизменяемые значения (`frozen=True, slots=True`) — их можно шарить между
-потоками, класть в ключи, логировать (кроме `Creds`) и сериализовать
-``dataclasses.asdict``. Всё, что имеет жизненный цикл (клиенты, сторы,
-браузеры), остаётся слоями выше.
-
-ТОЛЬКО stdlib. Перенесено из ``librarykit.contract`` БЕЗ
-изменения формы: порядок полей и дефолты те же, поэтому позиционные вызовы и
-уже записанные данные продолжают работать.
-"""
-from __future__ import annotations
-
-from collections.abc import Mapping
-from dataclasses import dataclass, field
-from typing import Any
-
-from corekit.context import DEFAULT_TENANT
-
-__all__ = [
-    "Creds",
-    "RequestBody",
-    "SessionRef",
-]
-
-
-@dataclass(frozen=True, slots=True)
-class SessionRef:
-    """Координаты сессии в `SessionStore`: profile / social / account-id.
-
-    Тройка ``profile``/``social``/``account_id`` однозначно адресует каталог
-    сессии ``<profile>/<social>/<account_id>/`` под корнем sessions. Без секретов —
-    это только ключ/путь, поэтому безопасно логировать и индексировать.
-
-    ``tenant`` — ЧЕТВЁРТАЯ (последняя, с дефолтом) координата: владелец сессии в
-    мультитенантном хосте. Поле добавлено В КОНЕЦ, поэтому позиционное
-    ``SessionRef(profile, social, account_id)`` и сравнение старых объектов
-    продолжают работать.
-
-    Координата ПОДКЛЮЧЕНА: при ``tenant != DEFAULT_TENANT`` каталог сессии
-    получает ведущий сегмент — ``<tenant>/<profile>/<social>/<account_id>/``, а
-    первичный ключ индекса — ``(tenant, profile, social, account_id)``. При
-    дефолтном ``"local"`` раскладка и ключ байт-в-байт прежние (сегмент не
-    добавляется), поэтому существующие сессии читаются как раньше. Пересборка
-    индекса из каталога — `SessionStore.reindex` (понимает обе глубины).
-    """
-
-    profile: str
-    social: str
-    account_id: str
-    tenant: str = DEFAULT_TENANT
-
-
-@dataclass(frozen=True, slots=True)
-class RequestBody:
-    """Тело RPC-запроса после `Codec.encode_request` (E1.T2): json XOR data.
-
-    Нейтральный носитель сериализованного payload между codec и транспортом:
-    `json` уходит в `Transport.request(json=...)` (httpx сам сериализует), а
-    `data` — сырое тело (bytes/str/form) для не-JSON envelope. Заполняется ровно
-    одно из двух; `headers` опц. добавляет codec-специфичные заголовки
-    (`Content-Type` и т.п.) к запросу.
-    """
-
-    json: Any | None = None
-    data: Any | None = None
-    headers: Mapping[str, str] = field(default_factory=dict)
-
-
-@dataclass(frozen=True, slots=True)
-class Creds:
-    """Секреты авторизации одной сессии (НЕ логировать, НЕ сериализовать в индекс).
-
-    Гибкий контейнер под разные `AuthMode`: токены (token-auth), refresh-токен
-    (oauth2), cookies (cookie-сессия), произвольные `extra` (например, подписи).
-    Все поля опциональны — заполняется то, что нужно конкретному режиму.
-    """
-
-    token: str | None = None
-    refresh_token: str | None = None
-    cookies: Mapping[str, str] = field(default_factory=dict)
-    extra: Mapping[str, Any] = field(default_factory=dict)