kompas-kernel 0.0.1__py3-none-any.whl

kompas_kernel/ksapi_static/facts.py

@@ -0,0 +1,132 @@
+"""Reusable syntax and installed-KsAPI facts, without product sandbox policy.
+
+The checker validates attribute call names, call arities and constants against an
+explicit :class:`KsapiInventory`. It does not know the ``run_python`` namespace,
+forbidden imports, dangerous builtins or connection policy, so an external developer
+can reuse these facts without inheriting Copilot's execution sandbox.
+"""
+
+from __future__ import annotations
+
+import ast
+from enum import StrEnum
+
+from kompas_kernel.ksapi_static.inventory import KsapiInventory
+from kompas_kernel.utils.validation import CustomModel
+
+# Python container methods are not KsAPI typos. Build the set mechanically so it
+# follows the runtime instead of becoming another hand-maintained inventory.
+_BUILTIN_METHOD_ALLOWLIST: frozenset[str] = frozenset(
+    name for builtin_type in (list, dict, str, set, frozenset, tuple, bytes, bytearray) for name in dir(builtin_type)
+)
+
+
+class KsapiViolationKind(StrEnum):
+    """A reusable syntax or installed-KsAPI fact violation."""
+
+    SYNTAX = "syntax"
+    UNKNOWN_KSAPI_METHOD = "unknown_ksapi_method"
+    KSAPI_ARITY = "ksapi_arity"
+    UNKNOWN_KSAPI_CONSTANT = "unknown_ksapi_constant"
+
+
+class KsapiViolation(CustomModel):
+    """One reusable static fact violation."""
+
+    kind: KsapiViolationKind
+    message: str
+
+
+class KsapiReport(CustomModel):
+    """Result of checking only syntax and facts from an installed KsAPI inventory."""
+
+    ok: bool
+    violations: tuple[KsapiViolation, ...]
+
+
+def check_ksapi_code(code: str, *, ksapi_inventory: KsapiInventory | None) -> KsapiReport:
+    """Check syntax and installed-KsAPI facts without applying product sandbox policy."""
+    try:
+        tree = ast.parse(code)
+    except SyntaxError as exc:
+        message = f"синтаксическая ошибка: {exc.msg} (строка {exc.lineno})"
+        violation = KsapiViolation(kind=KsapiViolationKind.SYNTAX, message=message)
+        return KsapiReport(ok=False, violations=(violation,))
+
+    violations = tuple(
+        violation
+        for node in ast.walk(tree)
+        for violation in collect_ksapi_violations(node, ksapi_inventory=ksapi_inventory)
+    )
+    return KsapiReport(ok=not violations, violations=violations)
+
+
+def collect_ksapi_violations(
+    node: ast.AST,
+    *,
+    ksapi_inventory: KsapiInventory | None,
+) -> tuple[KsapiViolation, ...]:
+    """Return installed-KsAPI fact violations contributed by one AST node."""
+    violations: list[KsapiViolation] = []
+    method_violation = _ksapi_method_violation(node, ksapi_inventory)
+    if method_violation is not None:
+        violations.append(method_violation)
+    constant_violation = _ksapi_constant_violation(node, ksapi_inventory)
+    if constant_violation is not None:
+        violations.append(constant_violation)
+    return tuple(violations)
+
+
+def _ksapi_method_violation(node: ast.AST, inventory: KsapiInventory | None) -> KsapiViolation | None:
+    """Validate ``x.Foo(...)`` by name and arity without trying to infer ``x``'s type."""
+    if inventory is None or not isinstance(node, ast.Call) or not isinstance(node.func, ast.Attribute):
+        return None
+    name = node.func.attr
+    if name in _BUILTIN_METHOD_ALLOWLIST:
+        return None
+    if name not in inventory.known_call_names:
+        return KsapiViolation(
+            kind=KsapiViolationKind.UNKNOWN_KSAPI_METHOD,
+            message=(
+                f"'{name}' не найден среди методов/классов ksAPI установленной сборки — "
+                "проверь имя (grep_ksapi_wrappers/ask_ksapi_expert)"
+            ),
+        )
+    allowed_arities = inventory.method_arities.get(name)
+    if allowed_arities is None:
+        return None
+    call_arity = _call_arg_count(node)
+    if call_arity is None or call_arity in allowed_arities:
+        return None
+    allowed = ", ".join(str(count) for count in sorted(allowed_arities))
+    return KsapiViolation(
+        kind=KsapiViolationKind.KSAPI_ARITY,
+        message=f"'{name}(...)' вызван с {call_arity} аргумент(ами) — у ksAPI допустимо: {allowed}",
+    )
+
+
+def _call_arg_count(node: ast.Call) -> int | None:
+    """Return a deterministic call arity, or ``None`` for ``*args``/``**kwargs``."""
+    if any(isinstance(arg, ast.Starred) for arg in node.args):
+        return None
+    if any(keyword.arg is None for keyword in node.keywords):
+        return None
+    return len(node.args) + len(node.keywords)
+
+
+def _ksapi_constant_violation(node: ast.AST, inventory: KsapiInventory | None) -> KsapiViolation | None:
+    """Validate ``constants.*`` and ``constants3d.*`` names against the inventory."""
+    if inventory is None or not isinstance(node, ast.Attribute) or not isinstance(node.value, ast.Name):
+        return None
+    namespace_name = node.value.id
+    if namespace_name == "constants3d" and node.attr not in inventory.constants3d_names:
+        return KsapiViolation(
+            kind=KsapiViolationKind.UNKNOWN_KSAPI_CONSTANT,
+            message=f"'constants3d.{node.attr}' не найдена среди констант установленной сборки",
+        )
+    if namespace_name == "constants" and node.attr not in inventory.constants_names:
+        return KsapiViolation(
+            kind=KsapiViolationKind.UNKNOWN_KSAPI_CONSTANT,
+            message=f"'constants.{node.attr}' не найдена среди констант установленной сборки",
+        )
+    return None

kompas_kernel/ksapi_static/inventory.py

@@ -0,0 +1,185 @@
+"""Инвентарь имён ksAPI установленной сборки — источник истины для гейта по именам.
+
+`build_ksapi_inventory` разбирает три generated wrapper-файла (`ksapi.py`/`constants.py`/
+`constants3d.py`) через `ast`, БЕЗ импорта модулей и без запуска КОМПАС. Пути к этим трём
+файлам сюда приходят уже РЕЗОЛВЛЕННЫМИ (`Path`, параметром) — модуль их не ищет и не
+резолвит сам: единственный вызов
+`kompas_kernel.ksapi_static.wrapper_grep.resolve_wrapper_paths` живёт в
+`core/composition.py::_wire_ksapi_inventory` (composition — orchestration wiring, ему
+можно импортировать любой слой), и та же пара путей идёт вторым потребителем в
+`build_wrapper_grep_toolset` эксперта (GPC1/GPC4/GPC8 — один резолвер на двух
+потребителей, не второй способ найти те же три файла). Резолвер и этот модуль физически
+лежат в одном пакете `kompas_kernel.ksapi_static` (E17.04c) — этот модуль МОГ БЫ
+импортировать `resolve_wrapper_paths` напрямую, но не делает этого: единственный вызов
+остаётся в composition wiring, чтобы инвентарь не резолвил пути дважды по двум разным
+вызовам.
+
+Строится ОДИН РАЗ при сборке приложения (`core/composition.py`) и передаётся в
+`features.ksapi_automation.gate.check_code` параметром — сам гейт с диска ничего не
+читает (GPC3).
+
+Арность метода — множество чисел аргументов ВЫЗОВА (без self/bound-инстанса), допустимых
+хотя бы одним известным определением этого имени. На измеренной сборке (см.
+`todo-tasks/tech-debt/gate-ksapi-name-check.md`) ни один non-dunder метод не использует
+`*args`/`**kwargs`/значения по умолчанию — арность там вырождается в одно число; код при
+этом остаётся корректным и для гипотетического метода с дефолтами (диапазон арностей).
+
+Конструкторы интерфейсов (`ksapi.IFoo(x)` — привычный cast сырого COM-объекта к типу)
+считаются ИЗВЕСТНЫМИ вызываемыми именами (`known_call_names` включает имена классов), но
+их арность НЕ проверяется: `__init__` — dunder, исключён из разбора методов по тем же
+правилам, что и остальные dunder'ы. Это осознанная граница, не недосмотр — проверка
+«вызов x.Foo(...) существует» не требует знать, что `Foo` конструктор, а не метод.
+
+`ksapi.py` держит известные имена не только в классах: 51 публичная функция МОДУЛЬНОГО
+уровня (`GetKompas`/`OpenKompas`/`RunLoop`/конвертеры массивов `To*Vector`/`From*Vector` и
+др., измерено на `kompas_bin_master/Release-x64`) вызываются точно так же — `ksapi.Foo(...)`
+— и гейт (`obj.Foo(...)`) их не отличит от метода интерфейса. Пропуск этих функций был
+дефектом: `ksapi.ToDoubleVector([1.0, 2.0])` — легальная передача массива через границу
+ksAPI, ложно ловилась как `UNKNOWN_KSAPI_METHOD`. Модульные функции разбираются наравне с
+методами (имя в `known_call_names`, арность — по факту сигнатуры, без self: `strip_leading=0`
+у `_call_arities`, в отличие от `strip_leading=1` у методов класса). Приватные (leading `_`,
+напр. `_initialize`) пропускаются — соглашение Python, не публичный API.
+"""
+
+from __future__ import annotations
+
+import ast
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+_DUNDER_PREFIX = "__"
+_PRIVATE_PREFIX = "_"
+
+
+@dataclass(frozen=True)
+class KsapiInventory:
+    """Снимок имён из `ksapi.py`/`constants.py`/`constants3d.py` установленной сборки.
+
+    Не Pydantic-модель: это внутренний build-time кеш композиции, не DTO на границе
+    (GPC4 — CustomModel зарезервирован для схем, пересекающих границу слоя/LLM).
+
+    - `known_call_names` — имена, легальные как `Foo` в `x.Foo(...)`: методы всех
+      интерфейсов + имена классов (конструкторы `ksapi.IFoo(...)`) + публичные функции
+      МОДУЛЬНОГО уровня `ksapi.py` (`GetKompas`, `ToDoubleVector`, ...) — гейт видит
+      `ksapi.Foo(...)` как атрибутный вызов и не отличает функцию модуля от метода
+      интерфейса. Без dunder-имён (методы) и без приватных (leading `_`, функции модуля).
+    - `method_arities` — имя -> множество допустимых чисел аргументов вызова (объединение
+      по ВСЕМ владельцам, где это имя встречается: интерфейсам-классам и/или самому модулю).
+      Имя без записи здесь — либо класс-конструктор, либо метод/функция с
+      неарифметизируемой сигнатурой (`*args`/`**kwargs`/`kwonly`) — для обоих случаев
+      арность не проверяется, только существование имени.
+    - `constants_names` — имена констант из `class constants:` в `constants.py` (2D/общие).
+    - `constants3d_names` — имена констант из `class constants:` в `constants3d.py` (3D).
+    """
+
+    known_call_names: frozenset[str]
+    method_arities: Mapping[str, frozenset[int]]
+    constants_names: frozenset[str]
+    constants3d_names: frozenset[str]
+
+
+def build_ksapi_inventory(*, ksapi_path: Path, constants_path: Path, constants3d_path: Path) -> KsapiInventory:
+    """Разобрать три wrapper-файла в инвентарь имён. Только `ast.parse`, никакого импорта.
+
+    Args:
+        ksapi_path: `ksapi.py` установленной сборки — классы-интерфейсы с их методами
+            И публичные функции модульного уровня (`GetKompas`, `ToDoubleVector`, ...).
+        constants_path: `constants.py` — 2D/общие константы внутри `class constants:`.
+        constants3d_path: `constants3d.py` — 3D-константы, тоже внутри `class constants:`
+            (то же имя класса в обоих файлах — различает их только путь файла, не имя
+            класса, поэтому файлы разбираются раздельно, а не по имени класса).
+    """
+    known_call_names, method_arities = _parse_ksapi_callables(ksapi_path)
+    constants_names = _parse_constant_names(constants_path)
+    constants3d_names = _parse_constant_names(constants3d_path)
+    return KsapiInventory(
+        known_call_names=known_call_names,
+        method_arities=method_arities,
+        constants_names=constants_names,
+        constants3d_names=constants3d_names,
+    )
+
+
+def _parse_ksapi_callables(path: Path) -> tuple[frozenset[str], Mapping[str, frozenset[int]]]:
+    """`ksapi.py` -> (все известные вызываемые имена, арности по имени).
+
+    Два источника «известного вызываемого имени», оба на верхнем уровне модуля:
+
+    - top-level классы — имя класса (конструктор `ksapi.IFoo(...)`) и non-dunder методы
+      в теле класса (арность без `self` — `strip_leading=1`);
+    - top-level функции модуля (`GetKompas`/`ToDoubleVector`/... — см. докстринг модуля):
+      арность без сдвига (`strip_leading=0`, у них нет `self`), приватные (leading `_`)
+      исключены.
+
+    В обоих случаях, если арность не считается детерминированно (`*args`/`**kwargs`/
+    keyword-only — на измеренной сборке таких 0, но код не полагается на это), имя всё
+    равно остаётся в `known_call_names`, просто без записи в `method_arities` —
+    существование и арность проверяются раздельно
+      (`kompas_kernel.ksapi_static.facts::_ksapi_method_violation`).
+    """
+    tree = ast.parse(path.read_text(encoding="utf-8"))
+    known_call_names: set[str] = set()
+    arities_by_name: dict[str, set[int]] = {}
+
+    def _record(name: str, args: ast.arguments, *, strip_leading: int) -> None:
+        known_call_names.add(name)
+        counts = _call_arities(args, strip_leading=strip_leading)
+        if counts:
+            arities_by_name.setdefault(name, set()).update(counts)
+
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.ClassDef):
+            known_call_names.add(node.name)
+            for item in node.body:
+                if isinstance(item, ast.FunctionDef) and not item.name.startswith(_DUNDER_PREFIX):
+                    _record(item.name, item.args, strip_leading=1)
+        elif isinstance(node, ast.FunctionDef) and not node.name.startswith(_PRIVATE_PREFIX):
+            _record(node.name, node.args, strip_leading=0)
+
+    method_arities = {name: frozenset(counts) for name, counts in arities_by_name.items()}
+    return frozenset(known_call_names), method_arities
+
+
+def _call_arities(args: ast.arguments, *, strip_leading: int) -> frozenset[int]:
+    """Возможные числа аргументов ВЫЗОВА одного определения — метода класса или функции модуля.
+
+    `strip_leading` — сколько ведущих позиционных параметров сигнатуры НЕ считать
+    аргументами вызова: 1 для метода класса (`self` передаётся вызовом через точку, в
+    скобках его нет), 0 для функции модуля (`ksapi.GetKompas()` — обычная функция, первый
+    параметр сигнатуры, если есть, реально нужно передавать в скобках).
+
+    Пустое множество означает «арность не считается детерминированно» (`*args`/`**kwargs`/
+    keyword-only параметры, либо параметров меньше, чем `strip_leading`) — вызывающая
+    сторона (`_parse_ksapi_callables`) тогда не добавляет запись в `method_arities`, но имя
+    всё равно остаётся среди `known_call_names`.
+    """
+    if args.vararg is not None or args.kwarg is not None or args.kwonlyargs:
+        return frozenset()
+    if len(args.args) < strip_leading:
+        return frozenset()  # меньше параметров, чем ведущих (self и т.п.) — форма неожиданная
+    total = len(args.args) - strip_leading
+    required = total - len(args.defaults)
+    return frozenset(range(required, total + 1))
+
+
+def _parse_constant_names(path: Path) -> frozenset[str]:
+    """Имена констант из ВСЕХ top-level классов файла (в обеих обёртках — ровно один
+    `class constants:`, но код не полагается на то, что класс единственный или так назван)."""
+    tree = ast.parse(path.read_text(encoding="utf-8"))
+    names: set[str] = set()
+    for node in ast.iter_child_nodes(tree):
+        if not isinstance(node, ast.ClassDef):
+            continue
+        for item in node.body:
+            names.update(_assign_target_names(item))
+    return frozenset(names)
+
+
+def _assign_target_names(item: ast.stmt) -> Iterator[str]:
+    if isinstance(item, ast.Assign):
+        for target in item.targets:
+            if isinstance(target, ast.Name):
+                yield target.id
+    elif isinstance(item, ast.AnnAssign) and isinstance(item.target, ast.Name):
+        yield item.target.id

kompas_kernel/ksapi_static/recipes.py

@@ -0,0 +1,114 @@
+"""Framework-free recipe catalog and deterministic lookup helpers.
+
+Каталог отдаётся ОРКЕСТРАТОРУ напрямую, а не через `ksapi_expert`: тело рецепта —
+исполняемый текст, который через шаг уходит в `build_geometry`/`run_python` дословно,
+поэтому пересказ под `output_type=str` его бы испортил тихо (гейт увидел бы валидный,
+но другой скрипт), а `pitfalls`/`provenance` потерялись бы на границе строки. Эксперт
+остаётся источником СИГНАТУР (RAG + grep generated-обёрток), где пересказ уместен.
+
+Правило каталога (не «все приёмы KsAPI подряд»): рецепт заводится там, где у агента
+НЕТ типизированного тула. Если приём уже закрыт портом `bridge`/`eyes`, рецепт на него
+— вредный дубль: он уводит модель в `run_python` мимо DTO, нормализации единиц и
+обработки `BridgeError`. Восемь таких дублей удалены 2026-07-26 (`read-assembly-
+components`, `select-and-zoom-component`, `measure-transient-distance`,
+`measure-face-distance`, `show-min-distance`, `probe-ray-neighbor`,
+`inspect-fastener-axis`, `find-neighbors-collision`).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import ConfigDict, Field
+
+from kompas_kernel.utils.validation import CustomModel
+
+
+class KsapiRecipeProvenance(CustomModel):
+    """Resolvable source plus the observed result that makes it evidence."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    source: str = Field(min_length=1)
+    evidence: str = Field(min_length=1)
+
+
+class KsapiRecipe(CustomModel):
+    """One derived recipe backed by an experiment or an explicitly recorded spike."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    recipe_id: str = Field(pattern=r"^[a-z][a-z0-9-]*$")
+    scenario: str = Field(min_length=1)
+    body: str = Field(min_length=1)
+    provenance: tuple[KsapiRecipeProvenance, ...] = Field(min_length=1)
+    pitfalls: tuple[str, ...] = ()
+
+
+class KsapiRecipeSummary(CustomModel):
+    """Cheap routing metadata returned before a full recipe is loaded."""
+
+    recipe_id: str
+    scenario: str
+
+
+class KsapiRecipeCatalog:
+    """Immutable in-memory index loaded once at agent composition."""
+
+    def __init__(self, *, recipes: tuple[KsapiRecipe, ...]) -> None:
+        by_id = {recipe.recipe_id: recipe for recipe in recipes}
+        if len(by_id) != len(recipes):
+            raise ValueError("recipe_id values must be unique")
+        self._recipes = recipes
+        self._by_id = by_id
+
+    def summaries(self) -> tuple[KsapiRecipeSummary, ...]:
+        return tuple(
+            KsapiRecipeSummary(recipe_id=recipe.recipe_id, scenario=recipe.scenario) for recipe in self._recipes
+        )
+
+    def get(self, recipe_id: str) -> KsapiRecipe:
+        try:
+            return self._by_id[recipe_id]
+        except KeyError as exc:
+            available = ", ".join(self._by_id)
+            raise KeyError(f"unknown recipe_id {recipe_id!r}; available: {available}") from exc
+
+
+def load_ksapi_recipe_catalog(*, recipes_dir: Path) -> KsapiRecipeCatalog:
+    """Load and validate all direct YAML children, failing fast on an invalid catalog.
+
+    A missing directory is a resource-provisioning problem (wrong install, stale
+    `KOMPAS_COPILOT__KSAPI_EXPERT__RECIPES_DIR` override), not a bare traceback: the
+    check below turns Python's `FileNotFoundError` into a message naming the exact
+    path and the two ways to fix it (same style as `_validate_frontend_dist` in
+    `transports/backend/app.py`).
+    """
+    if not recipes_dir.exists():
+        raise ValueError(
+            f"каталог KsAPI-рецептов не найден: {recipes_dir}; проверьте "
+            "ksapi_expert.recipes_dir (env KOMPAS_COPILOT__KSAPI_EXPERT__RECIPES_DIR) "
+            "или целостность установки"
+        )
+    root = recipes_dir.resolve(strict=True)
+    if not root.is_dir():
+        raise ValueError(f"KsAPI recipes path is not a directory: {root}")
+    paths = tuple(sorted(root.glob("*.yaml")))
+    if not paths:
+        raise ValueError(f"KsAPI recipes directory contains no .yaml files: {root}")
+    recipes: list[KsapiRecipe] = []
+    for path in paths:
+        try:
+            raw: object = yaml.safe_load(path.read_text(encoding="utf-8"))
+        except yaml.YAMLError as exc:
+            raise ValueError(f"invalid YAML in KsAPI recipe {path}: {exc}") from exc
+        try:
+            recipe = KsapiRecipe.model_validate(raw)
+        except ValueError as exc:
+            raise ValueError(f"invalid KsAPI recipe {path}: {exc}") from exc
+        if path.stem != recipe.recipe_id:
+            raise ValueError(f"KsAPI recipe filename must match recipe_id: {path.name!r} != {recipe.recipe_id!r}")
+        recipes.append(recipe)
+    recipes.sort(key=lambda recipe: recipe.recipe_id)
+    return KsapiRecipeCatalog(recipes=tuple(recipes))

kompas_kernel/ksapi_static/wrapper_grep.py

@@ -0,0 +1,83 @@
+"""Framework-free deterministic generated-wrapper lookup helpers."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from pydantic import Field
+
+from kompas_kernel.utils.validation import CustomModel
+
+WRAPPER_FILE_NAMES = ("ksapi.py", "constants.py", "constants3d.py")
+_IDENTIFIER_PATTERN = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
+
+
+class WrapperMatch(CustomModel):
+    """One exact identifier occurrence in an allowlisted generated wrapper."""
+
+    file: str
+    line: int = Field(ge=1)
+    text: str
+
+
+class WrapperGrepResult(CustomModel):
+    """Bounded deterministic matches from the current KOMPAS build."""
+
+    query: str
+    matches: tuple[WrapperMatch, ...]
+    truncated: bool
+
+
+def grep_wrapper_identifier(
+    *,
+    identifier: str,
+    wrapper_paths: tuple[Path, ...],
+    max_matches: int,
+) -> WrapperGrepResult:
+    """Return bounded line matches for one literal Python identifier."""
+    if _IDENTIFIER_PATTERN.fullmatch(identifier) is None:
+        raise ValueError("identifier must be one Python identifier, without regex or path syntax")
+    matches: list[WrapperMatch] = []
+    truncated = False
+    token_pattern = re.compile(rf"\b{re.escape(identifier)}\b")
+    for wrapper_path in wrapper_paths:
+        for line_number, line in enumerate(wrapper_path.read_text(encoding="utf-8").splitlines(), start=1):
+            if token_pattern.search(line) is None:
+                continue
+            if len(matches) == max_matches:
+                truncated = True
+                break
+            matches.append(
+                WrapperMatch(
+                    file=wrapper_path.name,
+                    line=line_number,
+                    text=line.strip(),
+                )
+            )
+        if truncated:
+            break
+    return WrapperGrepResult(query=identifier, matches=tuple(matches), truncated=truncated)
+
+
+def resolve_wrapper_paths(*, bin_dir: Path, file_names: tuple[str, ...]) -> tuple[Path, ...]:
+    """Resolve explicit wrapper file names directly under `bin_dir`, rejecting traversal.
+
+    Public (not module-private) because `ksapi_static/inventory.py` reuses the exact same
+    resolution — same allowlisted files, same `KOMPAS_BIN_DIR` root — to build the static
+    gate's name inventory (GPC4/GPC8: one resolver, not a second copy of this validation).
+    """
+    root = bin_dir.resolve(strict=True)
+    if not root.is_dir():
+        raise ValueError(f"KOMPAS_BIN_DIR is not a directory: {root}")
+    paths: list[Path] = []
+    for file_name in file_names:
+        if Path(file_name).name != file_name or Path(file_name).suffix != ".py":
+            raise ValueError(f"wrapper filename must be a direct .py child of KOMPAS_BIN_DIR: {file_name!r}")
+        path = (root / file_name).resolve(strict=True)
+        if path.parent != root:
+            raise ValueError(f"wrapper path escapes KOMPAS_BIN_DIR: {file_name!r}")
+        if not path.is_file():
+            raise ValueError(f"wrapper path is not a file: {path}")
+        paths.append(path)
+    return tuple(paths)

kompas_kernel/observability/__init__.py

@@ -0,0 +1 @@
+"""Framework-neutral structured logging runtime shared by product executables."""

kompas_kernel/observability/logger.py

@@ -0,0 +1,24 @@
+"""Logger and run-context primitives without application configuration."""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+import structlog
+import structlog.contextvars
+
+
+def new_run_id() -> str:
+    """Create an identifier that correlates logs and one run trace."""
+    return uuid.uuid4().hex
+
+
+def bind_run_id(run_id: str) -> None:
+    """Bind a run identifier to all subsequent structlog events in this context."""
+    structlog.contextvars.bind_contextvars(run_id=run_id)
+
+
+def get_logger(name: str | None = None) -> Any:  # structlog's lazy proxy is dynamically typed
+    """Return a lazy structlog logger which is safe to create before configuration."""
+    return structlog.get_logger(name)

kompas_kernel/observability/setup.py

@@ -0,0 +1,115 @@
+"""Explicit process-wide structlog configuration without application settings."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+from typing import Protocol, TextIO, runtime_checkable
+
+import structlog
+import structlog.contextvars
+import structlog.dev
+import structlog.processors
+import structlog.stdlib
+
+
+@dataclass(frozen=True, slots=True)
+class LoggingConfig:
+    """Caller-owned values required to configure one executable process."""
+
+    level: str
+    log_file: Path
+    max_bytes: int
+    backup_count: int
+    console_stream: TextIO
+    utf8_streams: tuple[object, ...]
+
+
+@runtime_checkable
+class _Utf8Reconfigurable(Protocol):
+    def reconfigure(self, *, encoding: str, errors: str) -> None: ...
+
+
+_configured = False
+
+
+def _ensure_utf8_streams(streams: tuple[object, ...]) -> None:
+    for stream in streams:
+        if isinstance(stream, _Utf8Reconfigurable):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+
+
+def _shared_processors() -> list[structlog.types.Processor]:
+    """Build the processor chain shared by file and console renderers."""
+    return [
+        structlog.contextvars.merge_contextvars,
+        structlog.stdlib.add_log_level,
+        structlog.processors.TimeStamper(fmt="iso"),
+        structlog.processors.StackInfoRenderer(),
+        structlog.processors.format_exc_info,
+    ]
+
+
+def _file_handler(config: LoggingConfig, level: int) -> logging.Handler | None:
+    """Create a rotating file handler, or omit it when its directory is unavailable."""
+    try:
+        config.log_file.parent.mkdir(parents=True, exist_ok=True)
+        handler: logging.Handler = RotatingFileHandler(
+            config.log_file,
+            maxBytes=config.max_bytes,
+            backupCount=config.backup_count,
+            encoding="utf-8",
+        )
+    except OSError:
+        return None
+    handler.setLevel(level)
+    handler.setFormatter(
+        structlog.stdlib.ProcessorFormatter(
+            processor=structlog.processors.JSONRenderer(ensure_ascii=False),
+            foreign_pre_chain=_shared_processors(),
+        )
+    )
+    return handler
+
+
+def _console_handler(config: LoggingConfig, level: int) -> logging.Handler:
+    handler = logging.StreamHandler(config.console_stream)
+    handler.setLevel(level)
+    handler.setFormatter(
+        structlog.stdlib.ProcessorFormatter(
+            processor=structlog.dev.ConsoleRenderer(colors=True, sort_keys=False),
+            foreign_pre_chain=_shared_processors(),
+        )
+    )
+    return handler
+
+
+def configure_observability(config: LoggingConfig) -> None:
+    """Configure stderr/file logging once for the current process."""
+    global _configured  # noqa: PLW0603
+    if _configured:
+        return
+
+    _ensure_utf8_streams(config.utf8_streams)
+    level = getattr(logging, config.level.upper(), logging.INFO)
+    structlog.configure(
+        processors=[
+            *_shared_processors(),
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        wrapper_class=structlog.stdlib.BoundLogger,
+        context_class=dict,
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(_console_handler(config, level))
+    file_handler = _file_handler(config, level)
+    if file_handler is not None:
+        root.addHandler(file_handler)
+    root.setLevel(level)
+    _configured = True