kompas-kernel 0.0.1__py3-none-any.whl

kompas_kernel/features/document_session/models.py

@@ -0,0 +1,311 @@
+"""DTO документной сессии: то, что возвращают `get_context`/`screenshot`/`checkpoint`/`restore`.
+
+`RunResult` (результат `run_python`) сюда не входит — он принадлежит
+`features/ksapi_automation/models.py` (см. `todo-tasks/E16-assembly-navigator/04b-*.md`),
+хотя и использует `GeoDigest` отсюда.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+from kompas_kernel.kompas.models import BBox, EntityRef, UnitsContract
+from kompas_kernel.utils.validation import CustomModel
+
+
+class GeoDigest(CustomModel):
+    """Дешёвый структурный отпечаток модели из ядра — без скриншота. Всё в мм/мм³.
+
+    Это «зрение без картинки»: число тел/граней/рёбер, габарит, объём. Дёшево по
+    токенам и достаточно, чтобы поймать «операция не изменила тело». `None` —
+    честный признак «нет данных» (пустой документ, объём не посчитан), не ноль.
+    """
+
+    body_count: int = Field(ge=0)
+    face_count: int = Field(ge=0)
+    edge_count: int = Field(ge=0)
+    volume_mm3: float | None = None
+    bbox: BBox | None = None
+
+
+class DocumentKind(StrEnum):
+    """Тип открытого документа КОМПАС (`ksDocumentTypeEnum`) — дискриминатор `DocumentContext`.
+
+    Дискриминируем по типу ДОКУМЕНТА В СЕССИИ, а не по расширению исходного файла:
+    импортированный `.step`/`.sat`/`.iges` открывается как деталь или сборка, и снимать
+    с него можно ровно то же. Значения перечислены полностью (никаких «молчаливых дыр» —
+    чертёж приходит как `DrawingContext`, а не как `UNKNOWN`).
+    """
+
+    PART = "part"
+    ASSEMBLY = "assembly"
+    DRAWING = "drawing"
+    FRAGMENT = "fragment"
+    SPECIFICATION = "spec"
+    TEXTUAL = "textual"
+    UNKNOWN = "unknown"
+
+
+class PartContext(CustomModel):
+    """3D-деталь (`ksDocumentPart`): структурный отпечаток геометрии.
+
+    Здесь `digest` честный — у детали свои тела/грани/рёбра. У КОРНЯ сборки их нет
+    (там только оси СК), поэтому digest сборке не даём — см. `AssemblyContext`.
+    """
+
+    doc_kind: Literal[DocumentKind.PART] = DocumentKind.PART
+    digest: GeoDigest
+
+
+class AssemblyContext(CustomModel):
+    """Сборка (`ksDocumentAssembly`): лёгкая сводка верхнего уровня.
+
+    `component_count`/`top_marking` — дёшево (`GetPartsArray`/`GetMarking`), без чтения
+    геометрии каждого компонента. Полный разбор компонентов — отдельный тул
+    `read_assembly_components`; здесь его не дублируем.
+    """
+
+    doc_kind: Literal[DocumentKind.ASSEMBLY] = DocumentKind.ASSEMBLY
+    component_count: int = Field(ge=0)
+    top_marking: str | None = None
+
+
+class DrawingContext(CustomModel):
+    """Чертёж (`ksDocumentDrawing`, `.cdw`). Пока без payload — вариант честный, не `UNKNOWN`."""
+
+    doc_kind: Literal[DocumentKind.DRAWING] = DocumentKind.DRAWING
+
+
+class FragmentContext(CustomModel):
+    """Фрагмент (`ksDocumentFragment`, `.frw`). Пока без payload."""
+
+    doc_kind: Literal[DocumentKind.FRAGMENT] = DocumentKind.FRAGMENT
+
+
+class SpecificationContext(CustomModel):
+    """Спецификация (`ksDocumentSpecification`, `.spw`). Пока без payload."""
+
+    doc_kind: Literal[DocumentKind.SPECIFICATION] = DocumentKind.SPECIFICATION
+
+
+class TextualContext(CustomModel):
+    """Текстовый документ (`ksDocumentTextual`, `.kdw`). Пока без payload."""
+
+    doc_kind: Literal[DocumentKind.TEXTUAL] = DocumentKind.TEXTUAL
+
+
+class UnknownDocumentContext(CustomModel):
+    """Неопознанный тип документа — несёт исходный код типа для диагностики."""
+
+    doc_kind: Literal[DocumentKind.UNKNOWN] = DocumentKind.UNKNOWN
+    raw_type_code: int
+    reason: str | None = None
+
+
+DocumentContext = Annotated[
+    PartContext
+    | AssemblyContext
+    | DrawingContext
+    | FragmentContext
+    | SpecificationContext
+    | TextualContext
+    | UnknownDocumentContext,
+    Field(discriminator="doc_kind"),
+]
+"""Полиморфный контекст документа: свой тип payload на каждый `DocumentKind`.
+
+Присоединяется к `CadContext` динамически через дискриминатор `doc_kind` (как
+`JsonPolymorphic`/`family` в других проектах). Так LLM не приходится гадать по
+пустому digest, что за документ открыт.
+"""
+
+
+def simple_document_context(kind: DocumentKind, raw_type_code: int) -> DocumentContext:
+    """Payload-less вариант для типов, где снимать пока нечего (2D/спец/текст).
+
+    `PART`/`ASSEMBLY` сюда не попадают — их читатель контекста строит явно, с payload.
+    Неизвестный код типа → `UnknownDocumentContext` с исходным кодом для диагностики.
+    """
+    match kind:
+        case DocumentKind.DRAWING:
+            return DrawingContext()
+        case DocumentKind.FRAGMENT:
+            return FragmentContext()
+        case DocumentKind.SPECIFICATION:
+            return SpecificationContext()
+        case DocumentKind.TEXTUAL:
+            return TextualContext()
+        case _:
+            return UnknownDocumentContext(raw_type_code=raw_type_code)
+
+
+class CadContext(CustomModel):
+    """Снимок текущего состояния сессии CAD для оркестратора (`get_context`).
+
+    `document_context` — полиморфный по типу документа (см. `DocumentContext`):
+    `None` ⇔ `document_open=False`. Раньше здесь висел плоский `digest`, который для
+    сборки читался как «пусто» и вводил в заблуждение — теперь digest живёт только
+    в `PartContext`, где он честный.
+
+    `document_name` — короткое имя документа (`IKompasDocument.GetName()`, имя файла с
+    расширением). У НЕСОХРАНЁННОГО документа КОМПАС отдаёт пустую строку и по имени, и
+    по пути (проверено живьём 2026-08-02 на новом `ksDocumentPart`, visible и invisible),
+    поэтому здесь у него честный `None`, а не выдуманное «БЕЗ ИМЕНИ». Имя читается из
+    сессии, а НЕ вычисляется из `document.document_path`: путь у безымянного документа
+    тоже пуст, и вывод одного поля из другого дал бы ложную уверенность.
+    """
+
+    connected: bool
+    app_version: str
+    document_open: bool
+    document: EntityRef | None = None
+    document_name: str | None = None
+    document_context: DocumentContext | None = None
+    units: UnitsContract = UnitsContract()
+
+    @property
+    def is_assembly(self) -> bool:
+        return isinstance(self.document_context, AssemblyContext)
+
+
+class ActiveDocument(CustomModel):
+    """Кто открыт в КОМПАС — и ничего больше. Дешёвое наблюдение без топологии.
+
+    Отдельный запрос от `CadContext` именно из-за цены: `get_context` для детали
+    перечисляет ВСЕ грани и рёбра (`GetObjects(o3d_face)`, `_count_bodies_via_faces`),
+    то есть стоит O(топологии) — живой замер 2026-08-02: 50 мс на детали из трёх
+    граней и тем больше, чем тяжелее модель. Здесь читаются четыре поля через
+    `GetActiveDocument`/`GetDocumentType`/`GetName`/`GetFullPath` — 4 мс и O(1)
+    независимо от сложности документа. Этого достаточно и для видимой модели
+    поверхности тулов, и для снимка контекста в промпте, а дайджест по требованию
+    отдаёт отдельный тул `geometry_digest`.
+
+    Инварианты те же, что у `CadContext`: документа нет → `document_open=False` и
+    остальные поля `None`; несохранённый документ → `doc_kind` есть, а `name`/`path`
+    равны `None` (КОМПАС отдаёт по нему пустые строки, проверено живьём).
+    """
+
+    model_config = CustomModel.model_config | {"frozen": True}
+
+    document_open: bool
+    doc_kind: DocumentKind | None = None
+    name: str | None = None
+    path: str | None = None
+
+
+NO_ACTIVE_DOCUMENT = ActiveDocument(document_open=False)
+"""Пустая сессия. Она же — стартовое значение до первого наблюдения (самое узкое)."""
+
+
+def active_document_of(context: CadContext) -> ActiveDocument:
+    """Спроецировать уже прочитанный полный контекст на его дешёвую часть.
+
+    Нужна там, где полный `CadContext` УЖЕ получен (ответ тула `get_context`): второй
+    поход в КОМПАС ради тех же четырёх полей был бы лишним.
+    """
+    if not context.document_open:
+        return NO_ACTIVE_DOCUMENT
+    return ActiveDocument(
+        document_open=True,
+        doc_kind=None if context.document_context is None else context.document_context.doc_kind,
+        name=context.document_name,
+        path=None if context.document is None else context.document.document_path,
+    )
+
+
+class ImageFormat(StrEnum):
+    """Формат файла скриншота; значение = и расширение файла, и хвост `image/<...>` media type.
+
+    Провайдеры принимают png/jpeg/gif/webp (в pydantic-ai это
+    `messages._image_format_lookup`) — BMP не берёт никто.
+    """
+
+    JPEG = "jpeg"
+
+
+SCREENSHOT_IMAGE_FORMAT = ImageFormat.JPEG
+"""Формат снимка окна КОМПАС — общий контракт сессии и тула (он же строит имя файла).
+
+JPEG, а не PNG: скриншот уезжает в модель на КАЖДОМ следующем шаге хода (он остаётся
+в истории) и целиком ложится в `trace.jsonl`. Живой замер окна 1312x1400: PNG 907 КБ
+против JPEG q=90 257 КБ при одинаково читаемом дереве построения — экономия в 3.5 раза
+на каждом запросе.
+"""
+
+
+class ScreenshotResult(CustomModel):
+    """Результат `screenshot`: путь к файлу-картинке + метаданные.
+
+    В `return_value` тула едет путь, а не байты: сама картинка уходит модели
+    отдельным `BinaryContent`, и дублировать её base64 в тексте ответа тула незачем.
+    `width`/`height` — размеры сохранённого JPEG (уже после уменьшения под окно
+    модели), а не исходного окна КОМПАС.
+    """
+
+    path: Path
+    image_format: ImageFormat
+    width: int = Field(gt=0)
+    height: int = Field(gt=0)
+
+
+class Checkpoint(CustomModel):
+    """Снимок состояния документа перед изменяющей операцией (страховка).
+
+    Снимок — это файл-копия документа (`path`) плюс дайджест на момент снятия.
+    `document_path` — стабильный хэндл исходного документа: именно этот файл
+    перезаписывается копией при `restore`, поэтому он обязателен и непустой.
+
+    Запись сериализуется в реестр сессии (`features/document_session/registry.py`),
+    откуда `restore` достаёт её по `checkpoint_id` — модель носит с собой только id,
+    а не три пути. Поэтому здесь же живут поля для человека, читающего реестр
+    глазами: `created_at` и `saved_untitled_document` (документ был безымянным и его
+    пришлось сохранить в рабочую область сессии, чтобы снимок вообще стал возможен).
+    """
+
+    checkpoint_id: str
+    path: Path
+    document_path: str
+    digest: GeoDigest
+    created_at: datetime
+    saved_untitled_document: bool
+
+
+class RestoreResult(CustomModel):
+    """Результат `restore`: доступный дайджест до, дайджест после и честность отката.
+
+    `matches_checkpoint` сравнивает дайджест ПОСЛЕ отката с дайджестом на момент
+    снятия — это и есть проверка «откат действительно вернул то состояние»; она
+    честна только потому, что дайджест снимка приходит из реестра, а не из аргументов
+    модели. `digest_before=None` означает, что повреждённое промежуточное состояние
+    прочитать не удалось; это не должно блокировать восстановление из снимка.
+    """
+
+    ok: bool
+    restored_from: Path
+    document_path: str
+    digest_before: GeoDigest | None
+    digest_after: GeoDigest
+    matches_checkpoint: bool
+
+
+class GuardStatus(StrEnum):
+    """Outcome of the shared checkpoint decorator around one Python operation."""
+
+    NOT_CAPTURED = "not_captured"
+    KEPT = "kept"
+    ROLLED_BACK = "rolled_back"
+    ROLLBACK_FAILED = "rollback_failed"
+
+
+class GuardReport(CustomModel):
+    """Common checkpoint/rollback report attached to specialized tool results."""
+
+    status: GuardStatus
+    detail: str
+    checkpoint_id: str | None = None
+    matches_checkpoint: bool | None = None

kompas_kernel/features/document_session/queries.py

@@ -0,0 +1,62 @@
+"""Framework-free public read API for document session, over `KompasSession`.
+
+No Pydantic AI, no `kompas_copilot.bridge` import — raw KsAPI context/topology reads
+live in `ksapi/context_reader.py`, screenshot capture in `ksapi/screenshot.py`; this
+module only wires them through session callbacks receiving `KompasContext` directly.
+
+CQS: everything here is a query — no document mutation. `screenshot` writes an image
+FILE (an external side effect for returning data to the caller, same category as
+`geometry_digest` computing a value), but it never changes CAD document state — that
+distinction is what routes `checkpoint`/`restore` to `commands.py` instead.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from kompas_kernel.features.document_session.digest import build_digest
+from kompas_kernel.features.document_session.ksapi import context_reader, screenshot
+from kompas_kernel.features.document_session.models import (
+    ActiveDocument,
+    CadContext,
+    GeoDigest,
+    ScreenshotResult,
+)
+from kompas_kernel.kompas.session import KompasContext, KompasSession
+
+
+async def get_context(session: KompasSession) -> CadContext:
+    """Снимок текущего состояния сессии CAD для оркестратора."""
+
+    def _operation(context: KompasContext) -> CadContext:
+        return context_reader.read_context(context.modules, context.app)
+
+    return await session.run(operation_name="document_session.get_context", operation=_operation)
+
+
+async def get_active_document(session: KompasSession) -> ActiveDocument:
+    """Дешёвое «кто открыт» без топологии — наблюдение хода (см. `ActiveDocument`)."""
+
+    def _operation(context: KompasContext) -> ActiveDocument:
+        return context_reader.read_active_document(context.modules, context.app)
+
+    return await session.run(operation_name="document_session.get_active_document", operation=_operation)
+
+
+async def geometry_digest(session: KompasSession) -> GeoDigest:
+    """Дешёвый структурный отпечаток активной 3D-детали."""
+
+    def _operation(context: KompasContext) -> GeoDigest:
+        raw = context_reader.read_active_topology(context.modules, context.app)
+        return build_digest(raw)
+
+    return await session.run(operation_name="document_session.geometry_digest", operation=_operation)
+
+
+async def screenshot_window(session: KompasSession, out_path: Path) -> ScreenshotResult:
+    """Снять окно КОМПАС целиком и сохранить его в `out_path`."""
+
+    def _operation(context: KompasContext) -> ScreenshotResult:
+        return screenshot.capture_window(context.app, context.modules, out_path)
+
+    return await session.run(operation_name="document_session.screenshot", operation=_operation)

kompas_kernel/features/document_session/registry.py

@@ -0,0 +1,101 @@
+"""Реестр чекпойнтов сессии: `checkpoints/index.json` под корнем рабочей области сессии.
+
+Зачем реестр поверх сырых `checkpoint`/`restore`:
+
+- **Место.** Снимки и сохранённые безымянные документы кладутся в рабочую область
+  СЕССИИ агента (`<workspace>/sessions/<session_id>/checkpoints|cad`), а не в каталог
+  логов: там агент видит их своими же тулами (`list_workspace`, `read_workspace_file`),
+  и там же пользователь ищет всё остальное, что произвёл прогон (todo, спул).
+- **Адресация.** Модель носит с собой ОДИН `checkpoint_id`, а пути и дайджест снимка
+  берутся из реестра. Раньше `restore` требовал три строковых аргумента, и дайджест
+  снимка не передавался вовсе — `matches_checkpoint` сравнивался с нулевым дайджестом
+  и всегда врал. Реестр — единственный источник истины о снятых чекпойнтах (GPC4).
+
+Реестр — `checkpoints/index.json`, обычный JSON (расширение входит в
+`WorkspaceSettings.text_extensions`), поэтому агент читает его штатным
+`read_workspace_file` и после сжатия контекста может найти забытый `checkpoint_id`
+без нового глагола. Запись атомарная (temp-рядом + `os.replace`, GPC5): процесс,
+упавший посреди записи, оставляет прежний валидный индекс.
+
+Чистый Python: ни KsAPI, ни pydantic-ai, ни `workspace` здесь нет.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from kompas_kernel.features.document_session.models import Checkpoint
+from kompas_kernel.utils.filesystem import atomic_write_text
+
+CHECKPOINTS_DIRNAME = "checkpoints"
+"""Подкаталог рабочей области сессии со снимками и реестром."""
+
+UNTITLED_DOCUMENTS_DIRNAME = "cad"
+"""Подкаталог рабочей области сессии для документов КОМПАС, сохранённых нами:
+безымянную деталь агента надо куда-то положить, прежде чем снимать с неё копию."""
+
+INDEX_FILENAME = "index.json"
+"""Имя файла реестра внутри `CHECKPOINTS_DIRNAME`."""
+
+_INDEX_KEY = "checkpoints"
+
+
+class CheckpointError(Exception):
+    """Отказ уровня реестра: неизвестный `checkpoint_id`, битый/нечитаемый `index.json`.
+
+    Отдельно от `KompasError` (сбой CAD) намеренно: тут КОМПАС ни при чём, и лечится
+    это иначе — посмотреть реестр и взять существующий id.
+    """
+
+
+class CheckpointRegistry:
+    """Список снятых чекпойнтов сессии в одном JSON-файле (порядок = порядок снятия).
+
+    Читается целиком при каждом обращении: файл заведомо маленький (десятки записей за
+    прогон), а «прочитать → дописать → атомарно заменить» переживает падение процесса
+    и параллельный процесс с тем же прогоном не рассматривается (одна сессия — один
+    агент, см. модель развёртывания в AGENTS.md).
+    """
+
+    def __init__(self, index_path: Path) -> None:
+        self._index_path = index_path
+
+    @property
+    def path(self) -> Path:
+        return self._index_path
+
+    def load(self) -> list[Checkpoint]:
+        """Все записи реестра в порядке снятия; файла ещё нет — пустой список (не ошибка)."""
+        if not self._index_path.is_file():
+            return []
+        raw = self._index_path.read_text(encoding="utf-8")
+        try:
+            payload = json.loads(raw)
+            entries = payload[_INDEX_KEY]
+            return [Checkpoint.model_validate(entry) for entry in entries]
+        except Exception as exc:
+            raise CheckpointError(
+                f"реестр чекпойнтов повреждён: {self._index_path} — {type(exc).__name__}: {exc}"
+            ) from exc
+
+    def append(self, checkpoint: Checkpoint) -> None:
+        """Дописать запись и атомарно заменить файл реестра."""
+        entries = [*self.load(), checkpoint]
+        payload = {_INDEX_KEY: [entry.model_dump(mode="json") for entry in entries]}
+        atomic_write_text(
+            self._index_path,
+            json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
+            create_parents=True,
+            newline=None,
+            sync=False,
+        )
+
+    def get(self, checkpoint_id: str) -> Checkpoint:
+        """Запись по id. Нет такой — `CheckpointError` со списком доступных id (не молча)."""
+        entries = self.load()
+        for entry in entries:
+            if entry.checkpoint_id == checkpoint_id:
+                return entry
+        known = ", ".join(entry.checkpoint_id for entry in entries) or "(реестр пуст)"
+        raise CheckpointError(f"чекпойнт {checkpoint_id!r} не найден в реестре сессии; известные id: {known}")

kompas_kernel/features/document_session/service.py

@@ -0,0 +1,128 @@
+"""`DocumentSessionService` — thin holder of one `KompasSession`, delegating to
+`queries`/`commands`.
+
+Exists solely because composition and its typed fake need one object implementing the
+narrow consumer-owned `DocumentSessionPort` Protocol declared in
+`core/capabilities/document_session.py` (same shape as `GeometryService`/`GeometryPort`)
+— no multi-step use case lives here beyond delegating. The session is a required
+dependency: this class neither creates nor closes it — the transport that built the
+session owns that lifecycle.
+
+Registry-facing checkpoint orchestration (capture → append to session registry,
+rollback → look up by `checkpoint_id`) is a SEPARATE class, `CheckpointService` (below):
+it depends on this service for the raw `checkpoint`/`restore` KsAPI calls plus a
+`session_dir` resolver for the session workspace, and is the only place that knows
+about the checkpoint registry file. Keeping it separate from `DocumentSessionService`
+avoids giving the raw query/command facade a workspace dependency it doesn't need.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from kompas_kernel.features.document_session import commands, queries
+from kompas_kernel.features.document_session.models import (
+    ActiveDocument,
+    CadContext,
+    Checkpoint,
+    GeoDigest,
+    RestoreResult,
+    ScreenshotResult,
+)
+from kompas_kernel.features.document_session.registry import (
+    CHECKPOINTS_DIRNAME,
+    INDEX_FILENAME,
+    UNTITLED_DOCUMENTS_DIRNAME,
+    CheckpointRegistry,
+)
+from kompas_kernel.kompas.session import KompasSession
+from kompas_kernel.observability.logger import get_logger
+from kompas_kernel.observability.taxonomy import LogDomain, LogEventType, event_name
+
+logger = get_logger(__name__)
+
+
+@runtime_checkable
+class RawCheckpointBackend(Protocol):
+    """Narrow consumer-owned contract `CheckpointService` needs from a document session.
+
+    Satisfied structurally by `DocumentSessionService` (below) in production and by a
+    typed fake in tests — `CheckpointService` never requires the concrete class.
+    """
+
+    async def checkpoint(self, *, checkpoint_dir: Path, untitled_document_dir: Path) -> Checkpoint: ...
+
+    async def restore(self, target: Checkpoint) -> RestoreResult: ...
+
+
+class DocumentSessionService:
+    """Delegates document-session queries/commands to `queries`/`commands` over one session."""
+
+    def __init__(self, session: KompasSession) -> None:
+        self._session = session
+
+    async def get_context(self) -> CadContext:
+        return await queries.get_context(self._session)
+
+    async def get_active_document(self) -> ActiveDocument:
+        return await queries.get_active_document(self._session)
+
+    async def geometry_digest(self) -> GeoDigest:
+        return await queries.geometry_digest(self._session)
+
+    async def screenshot(self, out_path: Path) -> ScreenshotResult:
+        return await queries.screenshot_window(self._session, out_path)
+
+    async def checkpoint(self, *, checkpoint_dir: Path, untitled_document_dir: Path) -> Checkpoint:
+        return await commands.checkpoint(
+            self._session, checkpoint_dir=checkpoint_dir, untitled_document_dir=untitled_document_dir
+        )
+
+    async def restore(self, target: Checkpoint) -> RestoreResult:
+        return await commands.restore(self._session, target)
+
+
+class CheckpointService:
+    """Registry-facing checkpoint orchestration over `DocumentSessionService`.
+
+    `session_dir` — чистая функция «session_id → корень рабочей области сессии»
+    (инъекция из composition root). Каталоги создаются лениво, на первом снимке.
+    """
+
+    def __init__(self, document_session: RawCheckpointBackend, *, session_dir: Callable[[str], Path]) -> None:
+        self._document_session = document_session
+        self._session_dir = session_dir
+
+    def registry(self, session_id: str) -> CheckpointRegistry:
+        """Реестр сессии — публичен: тесты и тулы показывают его путь пользователю."""
+        return CheckpointRegistry(self._session_dir(session_id) / CHECKPOINTS_DIRNAME / INDEX_FILENAME)
+
+    async def capture(self, session_id: str) -> Checkpoint:
+        """Снять снимок активного документа и записать его в реестр сессии."""
+        session_root = self._session_dir(session_id)
+        checkpoint = await self._document_session.checkpoint(
+            checkpoint_dir=session_root / CHECKPOINTS_DIRNAME,
+            untitled_document_dir=session_root / UNTITLED_DOCUMENTS_DIRNAME,
+        )
+        self.registry(session_id).append(checkpoint)
+        logger.info(
+            event_name(LogDomain.BRIDGE, "checkpoint_capture", LogEventType.COMPLETED),
+            session_id=session_id,
+            checkpoint_id=checkpoint.checkpoint_id,
+            saved_untitled_document=checkpoint.saved_untitled_document,
+        )
+        return checkpoint
+
+    async def rollback(self, session_id: str, checkpoint_id: str) -> RestoreResult:
+        """Откатить документ к записи реестра — дайджест снимка берётся оттуда же."""
+        target = self.registry(session_id).get(checkpoint_id)
+        result = await self._document_session.restore(target)
+        logger.info(
+            event_name(LogDomain.BRIDGE, "checkpoint_rollback", LogEventType.COMPLETED),
+            session_id=session_id,
+            checkpoint_id=checkpoint_id,
+            matches_checkpoint=result.matches_checkpoint,
+        )
+        return result

kompas_kernel/features/geometry_3d/__init__.py

@@ -0,0 +1,9 @@
+"""Geometry 3D feature slice: measurements, exact B-rep facts, dimension-line presentation.
+
+Framework-free (no Pydantic AI, no `kompas_copilot.bridge`): owns its DTO (`models.py`),
+raw KsAPI reader/measurements/presentation (`ksapi/`), public query/command API
+(`queries.py`/`commands.py`) over a `KompasSession`, and a thin service holder
+(`service.py`, tracks `IDistanceAngleMeasurement3D` references created by
+`show_distance_dimension`). Thin Pydantic AI registration lives in
+`core/capabilities/geometry_3d.py`.
+"""

kompas_kernel/features/geometry_3d/axis_math.py

@@ -0,0 +1,50 @@
+"""Shared pure axis-projection math for `wrench_zone.py` and `hex_detect.py`.
+
+Both need the same honest fact — "where along the fastener's axis (mm from
+`AxisLine.origin`, projected onto `AxisLine.direction`) does this point sit, and how far
+is it radially from the axis line" — for ГОСТ 13682-80 Черт. 5 (K/R) and hex-prism
+detection respectively. One formula, not two drifting copies (GPC8). No pydantic-ai, no
+bridge port calls: stdlib/math only, same boundary as its callers.
+"""
+
+from __future__ import annotations
+
+import math
+
+from kompas_kernel.features.geometry_3d.models import AxisLine
+from kompas_kernel.kompas.models import Point3D
+
+
+def unit_axis_direction(axis: AxisLine) -> tuple[float, float, float]:
+    """Normalize `axis.direction` — the bridge adapter does not (see `AxisLine` docstring).
+
+    Raises:
+        ValueError: `axis.direction` has zero length (a degenerate axis is a caller bug,
+            not a legitimate "no data" case).
+    """
+    direction = axis.direction
+    length = math.sqrt(direction.x_mm**2 + direction.y_mm**2 + direction.z_mm**2)
+    if length == 0:
+        raise ValueError("axis.direction must be non-zero")
+    return direction.x_mm / length, direction.y_mm / length, direction.z_mm / length
+
+
+def axial_and_radial_mm(point: Point3D, axis: AxisLine, unit: tuple[float, float, float]) -> tuple[float, float]:
+    """`(axial_mm, radial_mm)` of `point` relative to `axis.origin`, projected onto `unit`.
+
+    `axial_mm` — signed distance along the axis from `axis.origin`. `radial_mm` — distance
+    from `point` to the axis LINE (the perpendicular component), always non-negative.
+    `unit` — pre-normalized `axis.direction` (`unit_axis_direction`), passed in rather than
+    recomputed per point — callers project many points against the same axis in a loop.
+    """
+    origin = axis.origin
+    vx = point.x_mm - origin.x_mm
+    vy = point.y_mm - origin.y_mm
+    vz = point.z_mm - origin.z_mm
+    unit_x, unit_y, unit_z = unit
+    axial_mm = vx * unit_x + vy * unit_y + vz * unit_z
+    radial_x = vx - axial_mm * unit_x
+    radial_y = vy - axial_mm * unit_y
+    radial_z = vz - axial_mm * unit_z
+    radial_mm = math.sqrt(radial_x**2 + radial_y**2 + radial_z**2)
+    return axial_mm, radial_mm