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

{s_corekit-0.0.2 → s_corekit-0.0.3}/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.3}/PKG-INFO

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

{s_corekit-0.0.2 → s_corekit-0.0.3}/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.3"
 
 __all__ = [
     "__version__",
     # контекст исполнения
     "ExecutionContext",
+    "DEFAULT_STAGE",
     "DEFAULT_TENANT",
     # базовые DTO
     "SessionRef",

{s_corekit-0.0.2 → s_corekit-0.0.3}/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.3}/corekit/dto.py

@@ -16,7 +16,7 @@ from collections.abc import Mapping
 from dataclasses import dataclass, field
 from typing import Any
 
-from corekit.context import DEFAULT_TENANT
+from corekit.context import DEFAULT_STAGE, DEFAULT_TENANT
 
 __all__ = [
     "Creds",
@@ -44,12 +44,32 @@ class SessionRef:
     дефолтном ``"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)

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

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

s_corekit-0.0.3/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"]