kompas-kernel 0.0.1__py3-none-any.whl

kompas_kernel/features/geometry_3d/models.py

@@ -0,0 +1,216 @@
+"""DTO геометрии 3D — публичный контракт `queries.py`/`commands.py`/`GeometryPort`.
+
+Перенесено из `bridge/models/geometry.py` (`DistanceMeasurement`/`NeighborHit`/
+`NeighborsResult`/`AxisLine`/`FaceMesh`/`ComponentMesh`/`PlanarFaceFact`/`PlanarFaces`/
+`CylindricalFaceFact`/`CylindricalFaces`/`RayHit`) и `bridge/models/presentation.py`
+(`ShowDistanceResult`) — E16.04a. Framework-free: pydantic-схемы на `utils.validation.CustomModel`,
+`Point3D` берётся из `kompas_kernel.kompas.models` напрямую (feature slice не импортирует
+`kompas_copilot.bridge`, fitness-тест `tests/architecture/test_layer_boundaries.py`).
+
+Универсальные CAD-примитивы: измерение расстояния, соседи, ось, меш, ray-pick, точные
+B-rep грани, презентация размерных линий. Ни один не знает про ключи/ГОСТ/крепёж —
+сценарная логика живёт в `eyes`.
+"""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import Field, model_validator
+
+from kompas_kernel.kompas.models import Point3D
+from kompas_kernel.utils.validation import CustomModel
+
+
+class DistanceMeasurement(CustomModel):
+    """Минимальное расстояние между двумя компонентами сборки.
+
+    `point1`/`point2` — подтверждённые точки отрезка минимального расстояния из
+    `IDistanceAngleMeasurement3D.GetMinPoint1/2`. Это фактические координаты, в
+    отличие от `PickModelObjectsWithLimit`, где точки не используются как источник
+    истины для зазора.
+    """
+
+    component_identifier_1: str
+    component_identifier_2: str
+    distance_mm: float = Field(ge=0)
+    point1: Point3D
+    point2: Point3D
+    measure_result_code: int
+
+
+class NeighborHit(CustomModel):
+    """Один сосед компонента: идентификатор + зазор + точки минимума.
+
+    `distance_mm`/`point_on_target`/`point_on_neighbor` — из транзиентного
+    `IMeasurement3D` (part↔part), те же фактические координаты, что у
+    `DistanceMeasurement` (не заглушки ray-pick). `point_on_target` лежит на исходном
+    компоненте (крепеже), `point_on_neighbor` — на соседе.
+    """
+
+    component_identifier: str
+    component_name: str | None
+    distance_mm: float = Field(ge=0)
+    point_on_target: Point3D
+    point_on_neighbor: Point3D
+    measure_result_code: int
+
+
+class NeighborsResult(CustomModel):
+    """Соседи компонента в пределах `gap_mm`, по возрастанию зазора.
+
+    Механизм (детерминированный, read-only): bbox-предфильтр по `GetGabarit` отбирает
+    кандидатов дёшево (чистая математика), затем точный зазор до каждого считает
+    транзиентный `IMeasurement3D` part↔part — как `measure_min_distance`, но пачкой и с
+    отсевом по порогу. Универсальный примитив «что рядом с компонентом»; радиальная зона
+    ключа ГОСТ 13682-80 Черт. 5 — отдельный слой `eyes` поверх этого факта. `ICollision`
+    сюда сознательно НЕ берётся: он создаёт объект диагностики в дереве и пачкает документ
+    (`docs/recipes/ksapi-link.md` §«Спайк find-neighbors»), а этот путь чистый. Сам
+    компонент-цель в список не попадает.
+    """
+
+    target_identifier: str
+    gap_mm: float = Field(gt=0)
+    neighbors: list[NeighborHit]
+
+
+class AxisLine(CustomModel):
+    """Ось компонента: точка на оси + направление, глобальная СК документа, мм.
+
+    `origin` — `IPlacement3D.GetOrigin()`: для стандартного крепежа из библиотеки
+    это опорная плоскость под головкой/гайкой (подтверждено спайком 01). `direction`
+    — `IPlacement3D.GetVector(o3d_axisOZ)`, не ручной разбор `GetMatrix3D()`
+    (та же причина — не гадать про row-major/column-major раскладку матрицы).
+    `direction` не нормируется адаптером — отдаётся ровно то, что вернул KsAPI.
+    """
+
+    origin: Point3D
+    direction: Point3D
+
+
+class FaceMesh(CustomModel):
+    """Точки тесселляции одной грани компонента, глобальная СК документа, мм.
+
+    `face_index` — позиция грани в стабильном порядке перечисления граней
+    компонента (то же соглашение, что использует адаптер для индексации граней
+    внутри компонента); полезно для подсветки конкретной грани.
+    """
+
+    face_index: int = Field(ge=0)
+    points: list[Point3D]
+
+
+class ComponentMesh(CustomModel):
+    """Тесселляция всех граней компонента в глобальной СК документа, мм.
+
+    Грань без тесселляции (`IFace.GetTessellation()` вернул пусто/`None`) в список
+    не попадает — это не ошибка, а честный пропуск непосчитанной грани.
+    """
+
+    faces: list[FaceMesh]
+
+
+class PlanarFaceFact(CustomModel):
+    """Точный (не тесселлированный) факт об одной плоской грани компонента, глобальная СК, мм.
+
+    `radial_mm` — расстояние `IFace.GetDistanceToPoint()` от оси компонента (см.
+    `component_axis`) до плоскости этой грани, замеренное в осевой точке, где грань ещё
+    не обрезана (см. `component_planar_faces` докстринг) — честный перпендикуляр, не
+    приближение по вершинам. `corners` — угловые точки обрезанной границы грани
+    (`GetParamUMin/Max`×`GetParamVMin/Max` → `GetPoint`), уже в глобальной СК документа
+    (`IPart.TransformPoint`) — по ним вызывающий проецирует осевой диапазон грани на
+    ось, без обращения к тесселляции.
+    """
+
+    face_index: int = Field(ge=0)
+    radial_mm: float = Field(ge=0)
+    corners: list[Point3D]
+
+
+class PlanarFaces(CustomModel):
+    """Все плоские грани компонента, чья плоскость параллельна заданной оси, глобальная СК, мм.
+
+    Грани, чья плоскость НЕ параллельна оси (торцевые/скошенные грани — расстояние до
+    них зависит от точки на оси, единого радиального числа не существует), в список не
+    попадают — это фильтр на границе адаптера, не постобработка вызывающего.
+    """
+
+    faces: list[PlanarFaceFact]
+
+
+class CylindricalFaceFact(CustomModel):
+    """Точный (не тесселлированный) факт об одной цилиндрической грани, глобальная СК, мм.
+
+    `radial_mm` — расстояние от заданной оси (не обязательно оси самого компонента, см.
+    `component_cylindrical_faces`) до поверхности цилиндра: `abs(axis_to_axis_mm -
+    IFace.GetRadius())`, где `axis_to_axis_mm` — радиальный компонент точки на оси
+    цилиндра относительно заданной оси (та же математика `axial_and_radial_mm`, что и
+    для планарных фактов). Знак не нужен — расстояние от точки до окружности не зависит
+    от того, снаружи или внутри цилиндра лежит эта точка (`|d - R|` в обоих случаях).
+    `corners` — угловые точки обрезанной границы грани (те же `GetParamUMin/Max` ×
+    `GetParamVMin/Max` → `GetPoint`, что и у `PlanarFaceFact`), уже в глобальной СК —
+    по ним вызывающий проецирует осевой диапазон грани на ось.
+    """
+
+    face_index: int = Field(ge=0)
+    radial_mm: float = Field(ge=0)
+    corners: list[Point3D]
+
+
+class CylindricalFaces(CustomModel):
+    """Все цилиндрические грани компонента, чья ось параллельна заданной оси, глобальная СК, мм.
+
+    Грани, чья ось НЕ параллельна заданной оси (конус под углом, отверстие поперёк —
+    расстояние до них не сводится к одному радиальному числу), в список не попадают —
+    фильтр на границе адаптера, не постобработка вызывающего.
+    """
+
+    faces: list[CylindricalFaceFact]
+
+
+class RayHit(CustomModel):
+    """Результат геометрического ray-pick: только факт попадания в компонент.
+
+    Луч используется как read-only поиск соседних объектов. Координаты пересечения
+    намеренно не входят в DTO: спайк 03 показал заглушки на body/part-уровне, поэтому
+    точки луча не считаются надёжным фактом зазора.
+    """
+
+    hit: bool
+    component_identifier: str | None = None
+    component_name: str | None = None
+    model_object_type: int | None = None
+
+    @model_validator(mode="after")
+    def _check_hit_identifier(self) -> Self:
+        if self.hit and self.component_identifier is None:
+            raise ValueError("component_identifier is required when hit=True")
+        return self
+
+
+class ShowDistanceResult(CustomModel):
+    """Результат `show_distance_dimension`: постоянная размерная линия в 3D + честный факт.
+
+    `distance_mm`/`point1`/`point2` — тот же быстрый факт, что и `measure_min_distance`
+    (транзиентный `IMeasurement3D`, part↔part). `shown_value_mm` — то, что реально
+    показывает СОЗДАННАЯ постоянная фича `IDistanceAngleMeasurement3D` после `Update()`
+    (`GetLmin()`); она считает только `IFace↔IFace` (спайк 02), поэтому пара граней
+    резолвится по точкам минимума (ближайшая тесселлированная вершина на каждом
+    компоненте) — хордовая погрешность мешей может дать `shown_value_mm`, заметно
+    отличное от `distance_mm`; расхождение — честный сигнал, не скрывается.
+    `zoomed` — сработал ли зум по выделению (фичи-измерения или, если её выделение не
+    сработало, компонента-виновника — см. докстринг `ksapi/presentation.py`). `None` в
+    `shown_value_mm` означает, что постоянную фичу не удалось создать/посчитать (реализация
+    в этом случае бросает `KompasError`, поле оставлено `Optional` только для честности
+    контракта DTO).
+
+    Странность, зафиксированная и оставленная как есть (не чинить, E16.04a): `zoomed=False`
+    схлопывает две разные причины — «ничего не выделилось, зум не пробовали» и «выделилось,
+    но `ExecuteKompasCommand` вернул `False`». Поля, различающего их, в DTO нет.
+    """
+
+    distance_mm: float = Field(ge=0)
+    point1: Point3D
+    point2: Point3D
+    zoomed: bool
+    shown_value_mm: float | None = None

kompas_kernel/features/geometry_3d/queries.py

@@ -0,0 +1,96 @@
+"""Framework-free public read API for geometry 3D, over `KompasSession`.
+
+No Pydantic AI, no `kompas_copilot.bridge` import — the feature owns its own KsAPI
+measurements/component-geometry modules (`ksapi/measurements.py`,
+`ksapi/component_geometry.py`); this module only wires them through session callbacks
+that receive `KompasContext` directly (no migration-only `_ACTIVE_CONTEXT` seam).
+"""
+
+from __future__ import annotations
+
+from kompas_kernel.features.geometry_3d.ksapi import component_geometry, measurements
+from kompas_kernel.features.geometry_3d.models import (
+    AxisLine,
+    ComponentMesh,
+    CylindricalFaces,
+    DistanceMeasurement,
+    NeighborsResult,
+    PlanarFaces,
+    RayHit,
+)
+from kompas_kernel.kompas.models import Point3D
+from kompas_kernel.kompas.session import KompasContext, KompasSession
+
+
+async def measure_min_distance(
+    session: KompasSession,
+    component_identifier_1: str,
+    component_identifier_2: str,
+) -> DistanceMeasurement:
+    """Минимальное расстояние между двумя компонентами сборки (транзиентный `IMeasurement3D`)."""
+
+    def _operation(context: KompasContext) -> DistanceMeasurement:
+        return measurements.measure_min_distance(
+            context.modules, context.app, component_identifier_1, component_identifier_2
+        )
+
+    return await session.run(operation_name="geometry_3d.measure_min_distance", operation=_operation)
+
+
+async def find_neighbors(session: KompasSession, identifier: str, gap_mm: float) -> NeighborsResult:
+    """Компоненты в пределах `gap_mm` от компонента `identifier`, по возрастанию зазора."""
+
+    def _operation(context: KompasContext) -> NeighborsResult:
+        return measurements.find_neighbors(context.modules, context.app, identifier, gap_mm)
+
+    return await session.run(operation_name="geometry_3d.find_neighbors", operation=_operation)
+
+
+async def probe_ray(
+    session: KompasSession,
+    origin: Point3D,
+    direction: Point3D,
+    limit_mm: float,
+) -> RayHit:
+    """Найти компонент вдоль геометрической прямой (только факт попадания)."""
+
+    def _operation(context: KompasContext) -> RayHit:
+        return measurements.probe_ray(context.modules, context.app, origin, direction, limit_mm)
+
+    return await session.run(operation_name="geometry_3d.probe_ray", operation=_operation)
+
+
+async def component_axis(session: KompasSession, identifier: str) -> AxisLine:
+    """Ось компонента: origin + direction, глобальная СК документа, мм."""
+
+    def _operation(context: KompasContext) -> AxisLine:
+        return component_geometry.component_axis(context.modules, context.app, identifier)
+
+    return await session.run(operation_name="geometry_3d.component_axis", operation=_operation)
+
+
+async def component_mesh(session: KompasSession, identifier: str) -> ComponentMesh:
+    """Тесселляция всех граней компонента, глобальная СК документа, мм."""
+
+    def _operation(context: KompasContext) -> ComponentMesh:
+        return component_geometry.component_mesh(context.modules, context.app, identifier)
+
+    return await session.run(operation_name="geometry_3d.component_mesh", operation=_operation)
+
+
+async def component_planar_faces(session: KompasSession, identifier: str, axis: AxisLine) -> PlanarFaces:
+    """Точные плоские грани компонента, чья плоскость параллельна `axis`, глобальная СК, мм."""
+
+    def _operation(context: KompasContext) -> PlanarFaces:
+        return component_geometry.component_planar_faces(context.modules, context.app, identifier, axis)
+
+    return await session.run(operation_name="geometry_3d.component_planar_faces", operation=_operation)
+
+
+async def component_cylindrical_faces(session: KompasSession, identifier: str, axis: AxisLine) -> CylindricalFaces:
+    """Точные цилиндрические грани компонента, чья ось параллельна `axis`, глобальная СК, мм."""
+
+    def _operation(context: KompasContext) -> CylindricalFaces:
+        return component_geometry.component_cylindrical_faces(context.modules, context.app, identifier, axis)
+
+    return await session.run(operation_name="geometry_3d.component_cylindrical_faces", operation=_operation)

kompas_kernel/features/geometry_3d/service.py

@@ -0,0 +1,69 @@
+"""`GeometryService` — thin holder of one `KompasSession` + `ShownDimensionsState`.
+
+Exists solely because composition and its typed fake need one object implementing the
+narrow consumer-owned `GeometryPort` Protocol declared in `core/capabilities/geometry_3d.py`
+(same shape as `AssemblyNavigatorService`/`AssemblyNavigatorPort`) — no multi-step use case
+lives here beyond delegating to `queries`/`commands`. The session is a required dependency:
+this class neither creates nor closes it — the transport that built the session owns that
+lifecycle. `ShownDimensionsState` (list of `IDistanceAngleMeasurement3D` references created
+by `show_distance_dimension`) is owned here, one instance per service/session, replacing the
+field that used to live directly on `KompasKsApiAdapter`.
+"""
+
+from __future__ import annotations
+
+from kompas_kernel.features.geometry_3d import commands, queries
+from kompas_kernel.features.geometry_3d.commands import ShownDimensionsState
+from kompas_kernel.features.geometry_3d.models import (
+    AxisLine,
+    ComponentMesh,
+    CylindricalFaces,
+    DistanceMeasurement,
+    NeighborsResult,
+    PlanarFaces,
+    RayHit,
+    ShowDistanceResult,
+)
+from kompas_kernel.kompas.models import Point3D
+from kompas_kernel.kompas.session import KompasSession
+
+
+class GeometryService:
+    """Delegates geometry queries/commands to `queries`/`commands` over one session."""
+
+    def __init__(self, session: KompasSession) -> None:
+        self._session = session
+        self._state = ShownDimensionsState()
+
+    async def measure_min_distance(
+        self, component_identifier_1: str, component_identifier_2: str
+    ) -> DistanceMeasurement:
+        return await queries.measure_min_distance(self._session, component_identifier_1, component_identifier_2)
+
+    async def probe_ray(self, origin: Point3D, direction: Point3D, limit_mm: float) -> RayHit:
+        return await queries.probe_ray(self._session, origin, direction, limit_mm)
+
+    async def find_neighbors(self, identifier: str, gap_mm: float) -> NeighborsResult:
+        return await queries.find_neighbors(self._session, identifier, gap_mm)
+
+    async def component_axis(self, identifier: str) -> AxisLine:
+        return await queries.component_axis(self._session, identifier)
+
+    async def component_mesh(self, identifier: str) -> ComponentMesh:
+        return await queries.component_mesh(self._session, identifier)
+
+    async def component_planar_faces(self, identifier: str, axis: AxisLine) -> PlanarFaces:
+        return await queries.component_planar_faces(self._session, identifier, axis)
+
+    async def component_cylindrical_faces(self, identifier: str, axis: AxisLine) -> CylindricalFaces:
+        return await queries.component_cylindrical_faces(self._session, identifier, axis)
+
+    async def show_distance_dimension(
+        self, component_identifier_1: str, component_identifier_2: str
+    ) -> ShowDistanceResult:
+        return await commands.show_distance_dimension(
+            self._session, component_identifier_1, component_identifier_2, self._state
+        )
+
+    async def clear_dimensions(self) -> int:
+        return await commands.clear_dimensions(self._session, self._state)

kompas_kernel/features/geometry_3d/wrench_zone.py

@@ -0,0 +1,161 @@
+"""Pure radial-clearance geometry for ГОСТ 13682-80 Черт. 5 wrench-zone checks.
+
+Черт. 5 norms K and R (`standards/wrench_clearance.py`) are radial dimensions measured
+from the fastener axis (K=E — axis to a straight edge; R — pocket wall radius; see
+`docs/recipes/gost-13682-wrench-clearance.md` §2), not a surface-to-surface distance.
+This module computes the honest fact to compare against them: the minimum radial
+distance from a fastener's axis to a neighbor's tessellated mesh, restricted to the
+axial zone where a wrench actually needs room.
+
+No pydantic-ai, no bridge port calls: this module only consumes already-fetched
+`AxisLine`/`ComponentMesh` DTOs (the caller — the geometry toolset — fetches those through
+`GeometryPort` first) and returns a typed fact. stdlib/math only, so it stays fast
+even on a mesh with hundreds/thousands of points (no COM in the math).
+
+Черт. 6 (two-fastener wrench-clearance semantics: A2/E1 pairing) is out of scope here`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pydantic import Field
+
+from kompas_kernel.features.geometry_3d.axis_math import axial_and_radial_mm, unit_axis_direction
+from kompas_kernel.features.geometry_3d.models import (
+    AxisLine,
+    ComponentMesh,
+    CylindricalFaceFact,
+    PlanarFaceFact,
+)
+from kompas_kernel.kompas.models import Point3D
+from kompas_kernel.utils.validation import CustomModel
+
+
+class RadialDistance(CustomModel):
+    """Minimum radial distance from a fastener axis to a neighbor's mesh, in an axial zone.
+
+    `point`/`face_index` identify the neighbor mesh point/face that produced the
+    minimum — the culprit location for a verdict, `show_component`, or a future
+    dimension-line highlight (task 14).
+    """
+
+    min_radial_mm: float = Field(ge=0)
+    point: Point3D
+    face_index: int = Field(ge=0)
+
+
+def radial_distance(
+    axis: AxisLine,
+    mesh: ComponentMesh,
+    *,
+    z_min_mm: float,
+    z_max_mm: float,
+) -> RadialDistance | None:
+    """Minimum radial distance from `axis` to `mesh` points inside the axial zone.
+
+    Zone bounds are explicit caller-supplied parameters, not constants baked into this
+    module (GPC1): `z_min_mm`/`z_max_mm` are axial coordinates measured along
+    `axis.direction` from `axis.origin` — for a standard library fastener, `origin` is
+    the reference plane under the head/nut (see `AxisLine` docstring), but the sign of
+    "up" along the axis is not guaranteed, so this function does not assume it. Picking
+    the actual bounds (e.g. nut/head height plus a margin for wrench thickness) is the
+    caller's job, not this module's — see `core/capabilities/geometry_3d.py` (`measure_radial_distance`).
+
+    Geometry: for every mesh point `p`, project the vector `p - axis.origin` onto the
+    *unit* axis direction to get the axial coordinate `t` (`AxisLine.direction` is not
+    normalized by the bridge adapter — this function normalizes it itself, per the
+    `AxisLine` docstring). Points with `t` outside `[z_min_mm, z_max_mm]` are outside the
+    wrench zone and are skipped — this is how a same-axis bolt hole or washers get
+    excluded from the radial minimum, which is the whole point of the zone filter.
+    For points inside the zone, the radial component is
+    `(p - axis.origin) - t * unit_direction`; its norm is the radial distance that
+    ГОСТ 13682-80 Черт. 5 actually norms (K/R), not a surface-to-surface distance.
+
+    Returns the point with the smallest radial distance among the ones inside the zone,
+    or `None` if no mesh point falls inside the zone (empty zone — e.g. a neighbor
+    entirely outside the wrench's axial reach, or a mesh with no points at all).
+
+    Raises:
+        ValueError: `z_min_mm > z_max_mm`, or `axis.direction` has zero length (a
+            degenerate axis is a caller bug, not a legitimate "no data" case).
+    """
+    if z_min_mm > z_max_mm:
+        raise ValueError(f"z_min_mm ({z_min_mm:g}) must be <= z_max_mm ({z_max_mm:g})")
+    unit = unit_axis_direction(axis)
+
+    best: RadialDistance | None = None
+    for face in mesh.faces:
+        for point in face.points:
+            candidate = _radial_candidate_in_zone(point, axis, unit, (z_min_mm, z_max_mm), face.face_index)
+            if candidate is None:
+                continue
+            if best is None or candidate.min_radial_mm < best.min_radial_mm:
+                best = candidate
+    return best
+
+
+def _radial_candidate_in_zone(
+    point: Point3D,
+    axis: AxisLine,
+    unit: tuple[float, float, float],
+    zone: tuple[float, float],
+    face_index: int,
+) -> RadialDistance | None:
+    z_min_mm, z_max_mm = zone
+    axial_mm, radial_mm = axial_and_radial_mm(point, axis, unit)
+    if axial_mm < z_min_mm or axial_mm > z_max_mm:
+        return None
+    return RadialDistance(min_radial_mm=radial_mm, point=point, face_index=face_index)
+
+
+def radial_distance_from_exact_faces(
+    facts: Sequence[PlanarFaceFact | CylindricalFaceFact],
+    axis: AxisLine,
+    *,
+    z_min_mm: float,
+    z_max_mm: float,
+) -> RadialDistance | None:
+    """Minimum radial distance from `axis` among exact B-rep facts whose face overlaps the zone.
+
+    Fast-path counterpart of `radial_distance` (mesh vertices): `facts` come from
+    `GeometryInspector.component_planar_faces`/`component_cylindrical_faces` called with
+    a NEIGHBOR's identifier and the FASTENER's `axis` — each `fact.radial_mm` is already
+    the exact (no tessellation) perpendicular distance from `axis` to that whole face
+    (see those DTOs' docstrings — true for a planar face parallel to `axis`, and for a
+    cylindrical face whose own axis is parallel to `axis`, in both cases independent of
+    which point on the face or axis is picked).
+
+    The root-cause fix over `radial_distance`: a face is a candidate if its OWN AXIAL
+    EXTENT (the union of its `corners` projected onto `axis`, same projection as
+    `hex_detect.find_hex_prisms`) OVERLAPS `[z_min_mm, z_max_mm]` as an INTERVAL, not
+    "does some sampled point happen to land inside the zone". A real wall's corners
+    almost always span well beyond a narrow wrench-height zone on both ends, so interval
+    overlap reliably catches it; point-sampling (mesh vertices, only at a face's own
+    tessellation nodes) is what produced the honest-but-unlucky `empty_zone` this
+    function replaces as the primary path.
+
+    Returns the fact with the smallest `radial_mm` among overlapping candidates, or
+    `None` if none of `facts` overlaps the zone (a neighbor with no exact planar/
+    cylindrical wall near the fastener's axis in this height range — genuinely no B-rep
+    fast-path data; caller should fall back to `radial_distance` over the mesh).
+
+    Raises:
+        ValueError: `z_min_mm > z_max_mm` (a caller bug, not legitimate "no data").
+    """
+    if z_min_mm > z_max_mm:
+        raise ValueError(f"z_min_mm ({z_min_mm:g}) must be <= z_max_mm ({z_max_mm:g})")
+    unit = unit_axis_direction(axis)
+
+    best: RadialDistance | None = None
+    for fact in facts:
+        if not fact.corners:
+            continue
+        axial_values = [axial_and_radial_mm(corner, axis, unit)[0] for corner in fact.corners]
+        face_z_min = min(axial_values)
+        face_z_max = max(axial_values)
+        if face_z_max < z_min_mm or face_z_min > z_max_mm:
+            continue  # face's axial extent doesn't reach the query zone at all
+        if best is None or fact.radial_mm < best.min_radial_mm:
+            best = RadialDistance(min_radial_mm=fact.radial_mm, point=fact.corners[0], face_index=fact.face_index)
+    return best

kompas_kernel/features/ksapi_automation/__init__.py

@@ -0,0 +1,9 @@
+"""Guarded KsAPI automation capability."""
+
+from kompas_kernel.features.ksapi_automation.runner import (
+    GateRejectedError,
+    KsapiAutomationRunner,
+    KsapiCodeRunner,
+)
+
+__all__ = ["GateRejectedError", "KsapiAutomationRunner", "KsapiCodeRunner"]