kompas-kernel 0.0.1__py3-none-any.whl

kompas_kernel/features/ksapi_automation/gate.py

@@ -0,0 +1,282 @@
+"""Статический гейт v1: проверка сгенерированного Python ДО исполнения.
+
+Гейт v1 начинался намеренно ЛЁГКИМ (`execute_python` dev-trusted, см. `todo-tasks/E2-hands`):
+он ловит ОШИБКИ МОДЕЛИ, а не злонамеренный код. Полноценный sandbox — отдельный риск,
+утолщается после live smoke. Здесь только чистый статический анализ AST:
+
+- синтаксис (`ast.parse`);
+- политика импортов (нет файловой системы/сети/процессов/нового CAD-подключения);
+- нет создания нового подключения к КОМПАС (модель обязана использовать `app` из namespace);
+- нет опасных builtin-вызовов (`eval`/`exec`/`open`/`__import__`);
+- имя вызванного метода ksAPI существует в установленной сборке (`UNKNOWN_KSAPI_METHOD`);
+- число аргументов вызова совпадает хотя бы с одной известной арностью имени (`KSAPI_ARITY`);
+- имя константы `constants.*`/`constants3d.*` существует в установленной сборке
+  (`UNKNOWN_KSAPI_CONSTANT`);
+- читаемое имя определено — в namespace `run_python`, в самом коде или как builtin
+  (`UNDEFINED_NAME`).
+
+Три правила по ksAPI требуют `KsapiInventory` (см. `kompas_kernel.ksapi_static.inventory`) — без него
+(нет `KOMPAS_BIN_DIR`) они молча выключены, остальной гейт, включая `UNDEFINED_NAME`, работает
+как обычно (`todo-tasks/tech-debt/gate-ksapi-name-check.md`). Гейт НЕ выводит типы: «метод есть,
+но не у ЭТОГО интерфейса» не ловится — см. границы в том же файле техдолга.
+
+Живёт в `kompas_kernel.features.ksapi_automation` (единая точка проверки нужна ОБОИМ
+вызывающим `run_python` — сырой escape hatch `runner.py` и `build_geometry`
+`kompas_kernel.features.part_authoring.build_geometry`), см.
+`todo-tasks/tech-debt/gate-at-single-choke-point.md`. `part_authoring` импортирует отсюда
+`GateReport` — но ТОЛЬКО как DTO (`HandsResult.gate`) и для `validate_code` (сухой прогон
+без исполнения) — это осознанный явный порт/DTO слоя `ksapi_automation`, а не внутренности
+соседа.
+
+Sandbox-политика — единый источник (GPC1/GPC4): меняется здесь, нигде не
+дублируется. Переиспользуемые факты установленного KsAPI живут отдельно, физическим
+владельцем в `kompas_kernel.ksapi_static.facts` (E17.04c), и подключаются к тому же
+обходу AST без изменения порядка нарушений.
+Чистая функция `check_code` (GPC3): инвентарь приходит параметром, ничего не читает с диска
+и не исполняет.
+"""
+
+from __future__ import annotations
+
+import ast
+import builtins
+from enum import StrEnum
+from typing import assert_never
+
+from kompas_kernel.features.ksapi_automation.namespace import RUN_PYTHON_NAMESPACE_NAMES
+from kompas_kernel.ksapi_static.facts import (
+    KsapiViolation,
+    KsapiViolationKind,
+    collect_ksapi_violations,
+)
+from kompas_kernel.ksapi_static.inventory import KsapiInventory
+from kompas_kernel.utils.validation import CustomModel
+
+# Модули, которых не должно быть в коде построения. Namespace `run_python` уже даёт
+# app/doc/part/ksapi/constants/constants3d — импортировать SDK/IO не нужно.
+FORBIDDEN_IMPORT_PREFIXES: frozenset[str] = frozenset(
+    {
+        "os",
+        "sys",
+        "subprocess",
+        "socket",
+        "shutil",
+        "pathlib",
+        "importlib",
+        "ctypes",
+        "winreg",
+        "multiprocessing",
+        "threading",
+        "asyncio",
+        "requests",
+        "urllib",
+        "http",
+        "ftplib",
+        "smtplib",
+        "win32com",
+        "win32api",
+        "win32gui",
+        "win32ui",
+        "win32con",
+        "pythoncom",
+        "pywintypes",
+    }
+)
+
+# Вызовы, создающие НОВОЕ подключение к КОМПАС: модель обязана работать с готовым `app`.
+FORBIDDEN_CONNECTION_NAMES: frozenset[str] = frozenset(
+    {
+        "Dispatch",
+        "EnsureDispatch",
+        "GetActiveObject",
+        "GetKompas",
+        "OpenKompas",
+        "OpenKompasInvisible",
+        "CoInitialize",
+        "CoInitializeEx",
+        "CoCreateInstance",
+    }
+)
+
+# Опасные builtin-вызовы: динамическое исполнение и прямой доступ к ФС.
+FORBIDDEN_CALL_NAMES: frozenset[str] = frozenset({"eval", "exec", "compile", "__import__", "open"})
+
+# Имена, доступные в exec-namespace `run_python` без явного builtin/присваивания в коде.
+_BUILTIN_NAMES: frozenset[str] = frozenset(dir(builtins)) | {"__builtins__"}
+
+
+class GateViolationKind(StrEnum):
+    """Вид нарушения гейта."""
+
+    SYNTAX = "syntax"
+    FORBIDDEN_IMPORT = "forbidden_import"
+    NEW_CONNECTION = "new_connection"
+    FORBIDDEN_CALL = "forbidden_call"
+    UNKNOWN_KSAPI_METHOD = "unknown_ksapi_method"
+    KSAPI_ARITY = "ksapi_arity"
+    UNKNOWN_KSAPI_CONSTANT = "unknown_ksapi_constant"
+    UNDEFINED_NAME = "undefined_name"
+
+
+class GateViolation(CustomModel):
+    """Одно нарушение гейта: вид + человекочитаемая причина."""
+
+    kind: GateViolationKind
+    message: str
+
+
+class GateReport(CustomModel):
+    """Итог статической проверки: прошёл ли код и список нарушений (пустой при ok)."""
+
+    ok: bool
+    violations: tuple[GateViolation, ...] = ()
+
+
+def check_code(code: str, *, ksapi_inventory: KsapiInventory | None) -> GateReport:
+    """Статически проверить Python-код построения. Чистый запрос (GPC3).
+
+    При синтаксической ошибке возвращает отчёт с единственным нарушением SYNTAX
+    (AST дальше не обходится — обходить нечего).
+
+    Args:
+        code: Проверяемый Python-скрипт (тот же, что уйдёт в исполнение через
+            `KsapiAutomationRunner.run_python`).
+        ksapi_inventory: Инвентарь имён установленной сборки (`build_ksapi_inventory`),
+            собранный ОДИН РАЗ при сборке приложения и переданный сюда явно (GPC1) — гейт
+            сам с диска ничего не читает. `None` (нет `KOMPAS_BIN_DIR`) молча выключает
+            `UNKNOWN_KSAPI_METHOD`/`KSAPI_ARITY`/`UNKNOWN_KSAPI_CONSTANT`; `UNDEFINED_NAME`
+            и остальной гейт от инвентаря не зависят.
+    """
+    try:
+        tree = ast.parse(code)
+    except SyntaxError as exc:
+        message = f"синтаксическая ошибка: {exc.msg} (строка {exc.lineno})"
+        return GateReport(ok=False, violations=(GateViolation(kind=GateViolationKind.SYNTAX, message=message),))
+
+    violations: list[GateViolation] = []
+    for node in ast.walk(tree):
+        _collect_import_violation(node, violations)
+        _collect_call_violation(node, violations)
+        violations.extend(
+            _to_gate_violation(violation)
+            for violation in collect_ksapi_violations(node, ksapi_inventory=ksapi_inventory)
+        )
+    _collect_undefined_name_violations(tree, violations)
+    return GateReport(ok=not violations, violations=tuple(violations))
+
+
+def _collect_import_violation(node: ast.AST, violations: list[GateViolation]) -> None:
+    if isinstance(node, ast.Import):
+        for alias in node.names:
+            if alias.name.split(".")[0] in FORBIDDEN_IMPORT_PREFIXES:
+                violations.append(
+                    GateViolation(
+                        kind=GateViolationKind.FORBIDDEN_IMPORT,
+                        message=f"импорт '{alias.name}' запрещён: построение не требует ФС/сети/процессов/CAD runtime",
+                    )
+                )
+    elif isinstance(node, ast.ImportFrom):
+        module = node.module or ""
+        if module.split(".")[0] in FORBIDDEN_IMPORT_PREFIXES:
+            violations.append(
+                GateViolation(
+                    kind=GateViolationKind.FORBIDDEN_IMPORT,
+                    message=f"импорт из '{module}' запрещён: построение не требует ФС/сети/процессов/CAD runtime",
+                )
+            )
+
+
+def _collect_call_violation(node: ast.AST, violations: list[GateViolation]) -> None:
+    if not isinstance(node, ast.Call):
+        return
+    name = _called_name(node.func)
+    if name is None:
+        return
+    if name in FORBIDDEN_CONNECTION_NAMES:
+        violations.append(
+            GateViolation(
+                kind=GateViolationKind.NEW_CONNECTION,
+                message=f"вызов '{name}(...)' создаёт новое подключение к КОМПАС; используй готовый app из namespace",
+            )
+        )
+    elif name in FORBIDDEN_CALL_NAMES:
+        violations.append(
+            GateViolation(
+                kind=GateViolationKind.FORBIDDEN_CALL,
+                message=f"вызов '{name}(...)' запрещён в коде построения",
+            )
+        )
+
+
+def _to_gate_violation(violation: KsapiViolation) -> GateViolation:
+    """Translate a reusable KsAPI fact into the stable product gate DTO."""
+    match violation.kind:
+        case KsapiViolationKind.SYNTAX:
+            kind = GateViolationKind.SYNTAX
+        case KsapiViolationKind.UNKNOWN_KSAPI_METHOD:
+            kind = GateViolationKind.UNKNOWN_KSAPI_METHOD
+        case KsapiViolationKind.KSAPI_ARITY:
+            kind = GateViolationKind.KSAPI_ARITY
+        case KsapiViolationKind.UNKNOWN_KSAPI_CONSTANT:
+            kind = GateViolationKind.UNKNOWN_KSAPI_CONSTANT
+        case _:
+            assert_never(violation.kind)
+    return GateViolation(kind=kind, message=violation.message)
+
+
+def _collect_undefined_name_violations(tree: ast.AST, violations: list[GateViolation]) -> None:
+    """Читаемые имена, которых нет ни в namespace `run_python`, ни в коде, ни в builtins.
+
+    Плоский (без учёта области видимости/порядка) сбор связанных имён — сознательный выбор:
+    цель правила — ловить имена, которых в коде нет ВООБЩЕ (остатки старого API вроде
+    `part5`/`kompas5`), а не точный scope-анализ уровня pyflakes (см. «Границы» в
+    `todo-tasks/tech-debt/gate-ksapi-name-check.md`). Одно имя репортится один раз, даже
+    если прочитано в коде многократно.
+    """
+    bound = _bound_names(tree) | RUN_PYTHON_NAMESPACE_NAMES | _BUILTIN_NAMES
+    reported: set[str] = set()
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Name) or not isinstance(node.ctx, ast.Load):
+            continue
+        if node.id in bound or node.id in reported:
+            continue
+        reported.add(node.id)
+        violations.append(
+            GateViolation(
+                kind=GateViolationKind.UNDEFINED_NAME,
+                message=f"имя '{node.id}' нигде не определено: не в namespace run_python, не в коде, не builtin",
+            )
+        )
+
+
+def _bound_names(tree: ast.AST) -> frozenset[str]:
+    """Все имена, связанные ГДЕ УГОДНО в коде: присваивания, параметры, def/class, импорты.
+
+    `ast.walk` уже разворачивает цели `Tuple`/`List`/`Starred` (`a, b = ...`, `for a, b in
+    ...`) до отдельных `ast.Name(ctx=Store)` — отдельная рекурсия по целям не нужна.
+    """
+    bound: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
+            bound.add(node.id)
+        elif isinstance(node, ast.arg):
+            bound.add(node.arg)
+        elif isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef):
+            bound.add(node.name)
+        elif isinstance(node, ast.Import | ast.ImportFrom):
+            for alias in node.names:
+                bound.add(alias.asname or alias.name.split(".")[0])
+        elif isinstance(node, ast.ExceptHandler) and node.name is not None:
+            bound.add(node.name)
+        elif isinstance(node, ast.Global | ast.Nonlocal):
+            bound.update(node.names)
+    return frozenset(bound)
+
+
+def _called_name(func: ast.expr) -> str | None:
+    """Имя вызываемого: `foo(...)` -> 'foo', `obj.foo(...)` -> 'foo'. Иначе None."""
+    if isinstance(func, ast.Name):
+        return func.id
+    if isinstance(func, ast.Attribute):
+        return func.attr
+    return None

kompas_kernel/features/ksapi_automation/models.py

@@ -0,0 +1,75 @@
+"""DTO результата исполнения кода в сессии КОМПАС — `run_python`.
+
+Отдельно от `kompas_kernel.features.document_session.models`: `RunResult` — не документная сессия,
+а результат ОДНОГО прогона кода (гейт + исполнение), хотя и несёт `GeoDigest` оттуда.
+
+`RunPythonOutcome`/`RunPythonResult` — типизированный итог domain-операции
+`kompas_kernel.features.ksapi_automation.run_python.run_python` (E17.04f): закрытое множество
+транзакционных исходов по образцу `part_authoring.models.BuildOutcome`/`HandsResult`, НО не тот
+же набор. `RunResult.guard` остаётся на самом `RunResult`, а не только на `RunPythonResult.guard`,
+потому что model-facing поверхность (`core/capabilities/ksapi_automation.py::run_python`) обязана
+возвращать `RunResult | str` дословно как раньше — для success/script_error guard переносится
+на возвращаемый `RunResult` копированием, а не остаётся только во внутреннем DTO.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from kompas_kernel.features.document_session.models import GeoDigest, GuardReport
+from kompas_kernel.features.ksapi_automation.gate import GateReport
+from kompas_kernel.utils.validation import CustomModel
+
+
+class RunResult(CustomModel):
+    """Результат `run_python`: статус скрипта + дайджест до/после + честная дельта.
+
+    `ok` — отработал ли скрипт без исключения. `changed` — изменилась ли геометрия
+    по дайджесту (а не по словам скрипта). Их расхождение и есть сигнал «no-op,
+    который притворился успехом».
+    """
+
+    ok: bool
+    stdout: str = ""
+    error: str | None = None
+    digest_before: GeoDigest
+    digest_after: GeoDigest
+    changed: bool
+    guard: GuardReport | None = None
+
+
+class RunPythonOutcome(StrEnum):
+    """Исход domain-операции `run_python` — транзакционная категория, не сырой `RunResult`.
+
+    В отличие от `part_authoring.models.BuildOutcome`, здесь НЕТ отдельной категории для
+    «исполнилось, но без изменений»: `RunResult.ok=True` — легитимный успех run_python
+    независимо от `changed` (читающий скрипт коммитится — см. model-facing докстринг тула
+    `run_python`), тогда как для построения детали тот же случай (`changed=False`)
+    классифицируется как `BuildOutcome.NO_OP` с откатом. Смешать два набора значит поменять
+    поведение одной из двух операций (подробности —
+    `todo-tasks/E17-kompas-kernel/04f-canonical-checkpoint-decorator.md`, шаг 2).
+    """
+
+    SUCCESS = "success"  # код исполнился без исключения (RunResult.ok=True), независимо от changed
+    SCRIPT_ERROR = "script_error"  # код бросил исключение (RunResult.ok=False)
+    GATE_REJECTED = "gate_rejected"  # статический гейт отклонил код до исполнения
+    BRIDGE_ERROR = "bridge_error"  # сбой моста/КОМПАС вне гейта — исполнение либо обязательный снимок
+
+    # намеренно нет TIMEOUT: в отличие от build_geometry, run_python не оборачивает вызов
+    # в asyncio.wait_for — это поведение сохранено как есть, таймаут в исходах не заводим.
+
+
+class RunPythonResult(CustomModel):
+    """Типизированный итог domain-операции `run_python`: категория + сообщение + детали.
+
+    `run` присутствует, если код дошёл до исполнения (success/script_error). `gate`
+    присутствует, если код отклонён статически (gate_rejected). `guard` присутствует
+    всегда, когда результат прошёл через `@checkpointed` (весь публичный путь) — рассказывает,
+    был ли снят снимок и был ли выполнен откат.
+    """
+
+    outcome: RunPythonOutcome
+    message: str
+    run: RunResult | None = None
+    gate: GateReport | None = None
+    guard: GuardReport | None = None

kompas_kernel/features/ksapi_automation/namespace.py

@@ -0,0 +1,12 @@
+"""Единственный источник правды по namespace `run_python` (GPC1/GPC4).
+
+Ровно эти шесть имён кладёт в exec-namespace `execute_user_code`
+(`kompas_kernel.features.ksapi_automation.runner`), который проверяет себя на дрейф от
+этого множества. Статический гейт (`kompas_kernel.features.ksapi_automation.gate`,
+правило `UNDEFINED_NAME`) читает тот же список, чтобы не завести второй источник истины
+про namespace `run_python`.
+"""
+
+from __future__ import annotations
+
+RUN_PYTHON_NAMESPACE_NAMES: frozenset[str] = frozenset({"app", "doc", "part", "ksapi", "constants", "constants3d"})

kompas_kernel/features/ksapi_automation/run_python.py

@@ -0,0 +1,133 @@
+"""Checkpoint-decorated `run_python` — canonical mutation policy for the raw KsAPI escape hatch.
+
+Mirrors `kompas_kernel.features.part_authoring.build_geometry.run_build`: the shared
+`@checkpointed` decorator (`kompas_kernel.features.document_session.checkpointed`) is applied
+exactly ONCE, here, in the domain layer — transports (Copilot's Pydantic AI tool today, MCP
+tomorrow) call this operation and cannot bypass the checkpoint by calling the raw
+`KsapiCodeRunner` directly.
+
+Главный риск (E17.04f, см. `todo-tasks/E17-kompas-kernel/04f-canonical-checkpoint-decorator.md`,
+шаг 3): `GateRejectedError`/`KompasError` обязаны быть пойманы ВНУТРИ `_execute`, а не пролететь
+наружу. Если дать им пролететь, общий `@checkpointed` поймает их в `except BaseException`,
+выполнит ROLLBACK и перевозбудит исключение — то есть gate reject («документ не тронут») тихо
+превратится в rollback («документ откачен»). `_execute` ниже — та же роль, что `_execute` в
+`part_authoring.build_geometry`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, assert_never
+
+from kompas_kernel.features.document_session.checkpointed import (
+    CheckpointAction,
+    CheckpointDecision,
+    CheckpointGuard,
+    checkpointed,
+)
+from kompas_kernel.features.document_session.models import GuardReport
+from kompas_kernel.features.ksapi_automation.models import RunPythonOutcome, RunPythonResult
+from kompas_kernel.features.ksapi_automation.runner import GateRejectedError, KsapiCodeRunner
+from kompas_kernel.kompas.errors import KompasError
+
+
+async def _execute(runner: KsapiCodeRunner, code: str) -> RunPythonResult:
+    try:
+        run = await runner.run_python(code)
+    except GateRejectedError as exc:
+        return RunPythonResult(outcome=RunPythonOutcome.GATE_REJECTED, message=str(exc), gate=exc.report)
+    except KompasError as exc:
+        return RunPythonResult(outcome=RunPythonOutcome.BRIDGE_ERROR, message=str(exc))
+    if run.ok:
+        return RunPythonResult(
+            outcome=RunPythonOutcome.SUCCESS,
+            message="Python-скрипт завершился без исключения.",
+            run=run,
+        )
+    return RunPythonResult(
+        outcome=RunPythonOutcome.SCRIPT_ERROR,
+        message="Python-скрипт завершился ошибкой после начала исполнения.",
+        run=run,
+    )
+
+
+def _run_python_decision(result: RunPythonResult) -> CheckpointDecision:
+    match result.outcome:
+        case RunPythonOutcome.SUCCESS:
+            return CheckpointDecision(
+                action=CheckpointAction.COMMIT,
+                detail="Python-скрипт завершился без исключения.",
+            )
+        case RunPythonOutcome.GATE_REJECTED:
+            return CheckpointDecision(
+                action=CheckpointAction.NOT_EXECUTED,
+                detail="Код отклонён гейтом до исполнения — документ не менялся.",
+            )
+        case RunPythonOutcome.SCRIPT_ERROR:
+            return CheckpointDecision(
+                action=CheckpointAction.ROLLBACK,
+                detail="Исполнение Python-кода завершилось с ошибкой после начала исполнения.",
+            )
+        case RunPythonOutcome.BRIDGE_ERROR:
+            return CheckpointDecision(
+                action=CheckpointAction.ROLLBACK,
+                detail="Исполнение Python-кода завершилось с ошибкой моста.",
+            )
+        case _ as unreachable:
+            assert_never(unreachable)
+
+
+def _attach_run_python_guard(result: RunPythonResult, report: GuardReport) -> RunPythonResult:
+    return result.model_copy(update={"guard": report})
+
+
+def _blocked_run_python_result(report: GuardReport) -> RunPythonResult:
+    return RunPythonResult(
+        outcome=RunPythonOutcome.BRIDGE_ERROR,
+        message="обязательный снимок документа снять не удалось.",
+        guard=report,
+    )
+
+
+def _run_python_guard(
+    runner: KsapiCodeRunner, code: str, *, guard: CheckpointGuard, session_id: str
+) -> CheckpointGuard:
+    _ = (runner, code, session_id)
+    return guard
+
+
+def _run_python_session_id(runner: KsapiCodeRunner, code: str, *, guard: CheckpointGuard, session_id: str) -> str:
+    _ = (runner, code, guard)
+    return session_id
+
+
+@checkpointed(
+    guard=_run_python_guard,
+    session_id=_run_python_session_id,
+    decide=_run_python_decision,
+    attach_guard=_attach_run_python_guard,
+    blocked_result=_blocked_run_python_result,
+)
+async def run_python(runner: KsapiCodeRunner, code: str, *, guard: CheckpointGuard, session_id: str) -> RunPythonResult:
+    """Execute already-gated Python while the shared decorator owns every checkpoint side effect."""
+    _ = (guard, session_id)
+    return await _execute(runner, code)
+
+
+async def run_call[T](
+    runner: KsapiCodeRunner,
+    *,
+    operation_name: str,
+    call: Callable[..., T],
+    **kwargs: Any,
+) -> T:
+    """Run a trusted typed callback (bridge implementation) through the same session runner.
+
+    ``call`` — реализация моста из ``providers/kompas_api``: первым позиционным
+    аргументом получает `KompasContext`, остальные — ``**kwargs``. В отличие от
+    ``run_python`` здесь нет статического гейта и checkpoint: это пред-написанный
+    доверенный код, а не произвольный пользовательский сценарий; гейт — только
+    для кода модели (GPC1). Runtime-обёртка (``KompasError`` при сбое на воркере)
+    остаётся той же через ``KsapiCodeRunner.run_call``.
+    """
+    return await runner.run_call(operation_name=operation_name, call=call, **kwargs)

kompas_kernel/features/ksapi_automation/runner.py

@@ -0,0 +1,126 @@
+"""The single gate and namespace-exec choke point for KsAPI automation."""
+
+from __future__ import annotations
+
+import io
+from collections.abc import Callable, Mapping
+from contextlib import redirect_stdout
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from kompas_kernel.features.ksapi_automation.gate import GateReport, check_code
+from kompas_kernel.features.ksapi_automation.models import RunResult
+from kompas_kernel.features.ksapi_automation.namespace import RUN_PYTHON_NAMESPACE_NAMES
+from kompas_kernel.kompas.errors import KompasError
+from kompas_kernel.kompas.objects import as_document_3d, constants3d_class, constants_class
+from kompas_kernel.kompas.session import KompasContext
+from kompas_kernel.ksapi_static.inventory import KsapiInventory
+
+
+class KsapiCodeRunner(Protocol):
+    """Narrow consumer-owned contract shared by raw and guarded authoring paths."""
+
+    async def run_python(self, code: str) -> RunResult: ...
+
+    async def run_call[T](
+        self,
+        *,
+        operation_name: str,
+        call: Callable[..., T],
+        **kwargs: Any,
+    ) -> T: ...
+
+
+class _KsapiExecutionBackend(Protocol):
+    async def run_python(self, code: str) -> RunResult: ...
+
+    async def run_call[T](
+        self,
+        *,
+        operation_name: str,
+        call: Callable[..., T],
+        **kwargs: Any,
+    ) -> T: ...
+
+
+def _format_violations(report: GateReport) -> str:
+    lines = "\n".join(f"- {violation.kind.value}: {violation.message}" for violation in report.violations)
+    return f"код отклонён статическим гейтом до исполнения, нарушений — {len(report.violations)}:\n{lines}"
+
+
+class GateRejectedError(Exception):
+    """User code was rejected before it reached the KOMPAS session."""
+
+    def __init__(self, report: GateReport) -> None:
+        self.report = report
+        super().__init__(_format_violations(report))
+
+
+class KsapiAutomationRunner(KsapiCodeRunner):
+    """Apply the gate once, then delegate execution to the one session backend."""
+
+    def __init__(self, backend: _KsapiExecutionBackend, *, ksapi_inventory: KsapiInventory | None) -> None:
+        self._backend = backend
+        self._ksapi_inventory = ksapi_inventory
+
+    async def run_python(self, code: str) -> RunResult:
+        report = check_code(code, ksapi_inventory=self._ksapi_inventory)
+        if not report.ok:
+            raise GateRejectedError(report)
+        return await self._backend.run_python(code)
+
+    async def run_call[T](
+        self,
+        *,
+        operation_name: str,
+        call: Callable[..., T],
+        **kwargs: Any,
+    ) -> T:
+        """Delegate a trusted typed callback to the session backend — without the gate.
+
+        ``run_python`` гейтится как произвольный код модели; ``run_call`` — это
+        доверенные реализации моста (``providers/kompas_api``), описанные нами
+        же, поэтому статический гейт к ним неприменим (GPC1: один источник
+        правды для гейта, а не два дублирующих).
+        """
+        return await self._backend.run_call(operation_name=operation_name, call=call, **kwargs)
+
+
+@dataclass(frozen=True)
+class ExecOutcome:
+    """Result of user code execution inside the temporary KsAPI namespace."""
+
+    ok: bool
+    stdout: str
+    error: str | None
+
+
+def execute_user_code(context: KompasContext, code: str) -> ExecOutcome:
+    """Execute code with the one allowed namespace; raw handles never leave this call."""
+    doc = context.app.GetActiveDocument()
+    doc3d = as_document_3d(context.modules, doc)
+    part = None if doc3d is None else doc3d.GetTopPart()
+    namespace: dict[str, Any] = {
+        "app": context.app,
+        "doc": doc,
+        "part": part,
+        "ksapi": context.modules.ksapi,
+        "constants": constants_class(context.modules),
+        "constants3d": constants3d_class(context.modules),
+    }
+    _validate_namespace(namespace)
+    buffer = io.StringIO()
+    try:
+        with redirect_stdout(buffer):
+            exec(code, namespace)  # noqa: S102 - deliberate escape hatch behind the static gate.
+    except Exception as exc:
+        return ExecOutcome(ok=False, stdout=buffer.getvalue(), error=f"{type(exc).__name__}: {exc}")
+    return ExecOutcome(ok=True, stdout=buffer.getvalue(), error=None)
+
+
+def _validate_namespace(namespace: Mapping[str, object]) -> None:
+    if namespace.keys() != RUN_PYTHON_NAMESPACE_NAMES:
+        raise KompasError(
+            f"run_python namespace {sorted(namespace)} разошёлся с RUN_PYTHON_NAMESPACE_NAMES "
+            f"{sorted(RUN_PYTHON_NAMESPACE_NAMES)} — гейт и исполнение должны видеть один набор имён"
+        )