onec-interactive-runtime-core 0.1.19__py3-none-any.whl

onec_runtime/kernel.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import importlib.resources
+from pathlib import Path
+from urllib.parse import quote
+from uuid import UUID
+
+from onec_runtime.extension_bundle import EXTENSION_NAME, read_extension_manifest
+from onec_runtime.rdbg.models import ModuleLocation
+
+KERNEL_OBJECT_ID = "8fc91d24-20f5-4da4-8ff7-7a7c682f80f5"
+OBJECT_MODULE_PROPERTY_ID = "a637f77f-3840-441d-a1c3-699c8c5cb7e0"
+SERVICE_BREAKPOINT_MARKER = "@runtime-service-breakpoint"
+with importlib.resources.as_file(
+    importlib.resources.files("onec_runtime").joinpath(
+        "resources", "extension", "extension-manifest.json"
+    )
+) as _manifest_path:
+    _PRODUCT_BREAKPOINTS = read_extension_manifest(_manifest_path).breakpoints
+
+EXTENSION_OBJECT_ID = str(_PRODUCT_BREAKPOINTS.managed.object_id)
+MANAGED_APPLICATION_MODULE_PROPERTY_ID = "d22e852a-cf8a-4f77-8ccb-3548e7792bea"
+EXTENSION_BREAKPOINT_MARKER = "@runtime-extension-service-breakpoint"
+SESSION_MODULE_PROPERTY_ID = "9b7bbbae-9771-46f2-9e4d-2489e0ffc702"
+SESSION_STARTUP_BREAKPOINT_MARKER = "@runtime-session-startup-breakpoint"
+SERVER_COMMON_MODULE_OBJECT_ID = str(_PRODUCT_BREAKPOINTS.server_service.object_id)
+COMMON_MODULE_PROPERTY_ID = "d5963243-262e-4398-b4d7-fb16d06484f6"
+SERVER_EXTENSION_BREAKPOINT_MARKER = "@runtime-server-extension-service-breakpoint"
+SERVER_EXTENSION_ENTRY_BREAKPOINT_MARKER = "@runtime-server-extension-entry-breakpoint"
+SYNTHETIC_CAPTURE_A_MARKER = "@runtime-synthetic-capture-a"
+SYNTHETIC_CAPTURE_B_MARKER = "@runtime-synthetic-capture-b"
+SHIELDED_NESTED_CAPTURE_MARKER = "@runtime-shielded-nested-capture"
+USER_BREAKPOINT_MARKER = "@runtime-user-breakpoint"
+ZUP_GENERAL_PURPOSE_OBJECT_ID = "75e77f99-b9d1-4bc0-93aa-c77a93d760d3"
+ZUP_SERVER_CAPTURE_LINE = 875
+ZUP_SERVER_CAPTURE_B_LINE = 877
+
+
+def service_breakpoint_line(module_path: Path) -> int:
+    lines = module_path.read_text(encoding="utf-8").splitlines()
+    matches = [
+        index
+        for index, line in enumerate(lines, start=1)
+        if SERVICE_BREAKPOINT_MARKER in line
+    ]
+    if len(matches) != 1:
+        raise ValueError(
+            f"Expected exactly one {SERVICE_BREAKPOINT_MARKER} marker, found {len(matches)}"
+        )
+    marker_line = lines[matches[0] - 1]
+    if marker_line.lstrip().startswith("//") or (
+        ";" not in marker_line and " Тогда" not in marker_line
+    ):
+        raise ValueError(
+            "The service breakpoint marker must be on an executable BSL line"
+        )
+    return matches[0]
+
+
+def external_module_url(epf_path: Path) -> str:
+    normalized = str(epf_path.resolve()).replace("\\", "/")
+    return "file://" + quote(normalized, safe="/:")
+
+
+def extension_breakpoint_line(module_path: Path) -> int:
+    lines = module_path.read_text(encoding="utf-8-sig").splitlines()
+    matches = [
+        index
+        for index, line in enumerate(lines, start=1)
+        if EXTENSION_BREAKPOINT_MARKER in line
+    ]
+    if len(matches) != 1:
+        raise ValueError(
+            f"Expected exactly one {EXTENSION_BREAKPOINT_MARKER} marker, found {len(matches)}"
+        )
+    return matches[0]
+
+
+def server_extension_breakpoint_line(module_path: Path) -> int:
+    lines = module_path.read_text(encoding="utf-8-sig").splitlines()
+    matches = [
+        index
+        for index, line in enumerate(lines, start=1)
+        if SERVER_EXTENSION_BREAKPOINT_MARKER in line
+    ]
+    if len(matches) != 1:
+        raise ValueError(
+            f"Expected exactly one {SERVER_EXTENSION_BREAKPOINT_MARKER} marker, found {len(matches)}"
+        )
+    return matches[0]
+
+
+def server_extension_entry_breakpoint_line(module_path: Path) -> int:
+    lines = module_path.read_text(encoding="utf-8-sig").splitlines()
+    matches = [
+        index
+        for index, line in enumerate(lines, start=1)
+        if SERVER_EXTENSION_ENTRY_BREAKPOINT_MARKER in line
+    ]
+    if len(matches) != 1:
+        raise ValueError(
+            f"Expected exactly one {SERVER_EXTENSION_ENTRY_BREAKPOINT_MARKER} "
+            f"marker, found {len(matches)}"
+        )
+    marker_line = lines[matches[0] - 1]
+    if marker_line.lstrip().startswith("//") or ";" not in marker_line:
+        raise ValueError("The server entry breakpoint marker must be executable")
+    return matches[0]
+
+
+def session_extension_breakpoint_line(module_path: Path) -> int:
+    lines = module_path.read_text(encoding="utf-8-sig").splitlines()
+    matches = [
+        index
+        for index, line in enumerate(lines, start=1)
+        if SESSION_STARTUP_BREAKPOINT_MARKER in line
+    ]
+    if len(matches) != 1:
+        raise ValueError(
+            f"Expected exactly one {SESSION_STARTUP_BREAKPOINT_MARKER} marker, "
+            f"found {len(matches)}"
+        )
+    marker_line = lines[matches[0] - 1]
+    if marker_line.lstrip().startswith("//") or " Тогда" not in marker_line:
+        raise ValueError("The session startup marker must be on an executable BSL line")
+    return matches[0]
+
+
+def _server_module_marker_location(
+    module_path: Path,
+    marker: str,
+) -> ModuleLocation:
+    lines = module_path.read_text(encoding="utf-8-sig").splitlines()
+    matches = [index for index, line in enumerate(lines, start=1) if marker in line]
+    if len(matches) != 1:
+        raise ValueError(f"Expected exactly one {marker} marker, found {len(matches)}")
+    marker_line = lines[matches[0] - 1]
+    if marker_line.lstrip().startswith("//") or (
+        ";" not in marker_line and " Тогда" not in marker_line
+    ):
+        raise ValueError(f"Runtime marker {marker} must be executable")
+    return ModuleLocation(
+        "ExtensionModule",
+        "",
+        UUID(SERVER_COMMON_MODULE_OBJECT_ID),
+        UUID(COMMON_MODULE_PROPERTY_ID),
+        matches[0],
+        EXTENSION_NAME,
+    )
+
+
+def synthetic_capture_locations(
+    module_path: Path,
+) -> tuple[ModuleLocation, ModuleLocation]:
+    return _server_module_marker_location(
+        module_path,
+        SYNTHETIC_CAPTURE_A_MARKER,
+    ), _server_module_marker_location(module_path, SYNTHETIC_CAPTURE_B_MARKER)
+
+
+def shielded_capture_location(module_path: Path) -> ModuleLocation:
+    return _server_module_marker_location(module_path, SHIELDED_NESTED_CAPTURE_MARKER)
+
+
+def user_breakpoint_location(module_path: Path) -> ModuleLocation:
+    return _server_module_marker_location(module_path, USER_BREAKPOINT_MARKER)
+
+
+def zup_server_capture_location(
+    *,
+    line: int = ZUP_SERVER_CAPTURE_LINE,
+) -> ModuleLocation:
+    return ModuleLocation(
+        module_type="ConfigModule",
+        url="",
+        object_id=UUID(ZUP_GENERAL_PURPOSE_OBJECT_ID),
+        property_id=UUID(COMMON_MODULE_PROPERTY_ID),
+        line=line,
+    )

onec_runtime/lease.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from math import isfinite
+from uuid import UUID
+
+from onec_runtime.errors import (
+    LeaseConflict,
+    LeaseExpired,
+    StaleLeaseEpoch,
+    StaleRuntimeGeneration,
+)
+from onec_runtime.supervisor_model import LeaseHandle
+
+
+# Server-owned policy cap; permits the supervised live phase lease of 95 seconds.
+MAX_LEASE_TTL_S = 120.0
+
+
+def validate_lease_ttl(ttl_s: object) -> float:
+    if type(ttl_s) is int:
+        if ttl_s <= 0 or ttl_s > MAX_LEASE_TTL_S:
+            raise ValueError(
+                f"ttl_s must be greater than 0 and at most {MAX_LEASE_TTL_S}"
+            )
+        return float(ttl_s)
+    if type(ttl_s) is not float or not isfinite(ttl_s):
+        raise ValueError("ttl_s must be an exact finite built-in number")
+    if ttl_s <= 0 or ttl_s > MAX_LEASE_TTL_S:
+        raise ValueError(
+            f"ttl_s must be greater than 0 and at most {MAX_LEASE_TTL_S}"
+        )
+    return ttl_s
+
+
+@dataclass(frozen=True, slots=True)
+class LeaseStatus:
+    owner_id: UUID | None
+    lease_epoch: int | None
+    expires_in_s: float | None
+    expired: bool
+
+
+class LeaseAuthority:
+    """Issues the single mutating-owner lease for one runtime generation."""
+
+    def __init__(self, generation_id: int, *, clock: Callable[[], float]) -> None:
+        self._generation_id = generation_id
+        self._clock = clock
+        self._active: LeaseHandle | None = None
+        self._deadline: float | None = None
+        self._expired = False
+        self._next_epoch = 1
+        self._expiry_reported = False
+
+    def grant(self, owner_id: UUID, *, ttl_s: object) -> LeaseHandle:
+        validated_ttl_s = validate_lease_ttl(ttl_s)
+        if self._active is not None:
+            self._raise_if_expired()
+            if self._active.owner_id == owner_id:
+                return self._active
+            raise LeaseConflict("Another owner holds this generation lease")
+        if self._expired:
+            raise LeaseExpired("The generation lease has expired")
+
+        self._active = LeaseHandle(self._generation_id, owner_id, self._next_epoch)
+        self._next_epoch += 1
+        self._deadline = self._clock() + validated_ttl_s
+        return self._active
+
+    def renew(self, handle: LeaseHandle, *, ttl_s: object) -> LeaseHandle:
+        active = self._require_valid_handle(handle)
+        validated_ttl_s = validate_lease_ttl(ttl_s)
+        self._deadline = self._clock() + validated_ttl_s
+        return active
+
+    def validate(self, handle: LeaseHandle) -> LeaseHandle:
+        return self._require_valid_handle(handle)
+
+    def expire_if_due(self) -> LeaseHandle | None:
+        if self._active is None or self._expiry_reported:
+            return None
+        if not self._expired:
+            deadline = self._deadline
+            if deadline is None or self._clock() < deadline:
+                return None
+            self._expired = True
+        self._expiry_reported = True
+        return self._active
+
+    def status(self) -> LeaseStatus:
+        if self._active is None:
+            return LeaseStatus(None, None, None, self._expired)
+        deadline = self._deadline
+        if deadline is None:
+            return LeaseStatus(self._active.owner_id, self._active.lease_epoch, None, True)
+        remaining = max(0.0, deadline - self._clock())
+        return LeaseStatus(
+            self._active.owner_id,
+            self._active.lease_epoch,
+            remaining,
+            self._expired or remaining == 0.0,
+        )
+
+    def _require_valid_handle(self, handle: LeaseHandle) -> LeaseHandle:
+        if handle.generation_id != self._generation_id:
+            raise StaleRuntimeGeneration(
+                f"Generation {handle.generation_id} is no longer current"
+            )
+        active = self._active
+        if active is None or handle.owner_id != active.owner_id:
+            raise LeaseConflict("The supplied owner does not hold this lease")
+        if handle.lease_epoch != active.lease_epoch:
+            raise StaleLeaseEpoch("The supplied lease epoch is not current")
+        self._raise_if_expired()
+        return active
+
+    def _raise_if_expired(self) -> None:
+        deadline = self._deadline
+        if self._expired or deadline is None or self._clock() >= deadline:
+            self._expired = True
+            raise LeaseExpired("The generation lease has expired")

onec_runtime/observation.py

@@ -0,0 +1,287 @@
+"""Bounded, expression-free observation requests for agent operations."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+MAX_OBSERVATIONS = 100
+MAX_SELECTION_LIMIT = 10_000
+MAX_COLUMNS = 100
+
+
+class ObservationSourceKind(StrEnum):
+    CONTEXT_BINDING = "context_binding"
+    FRAME_LOCAL = "frame_local"
+    TEMPORARY_TABLE = "temporary_table"
+    TEMPORARY_TABLE_MANAGER = "temporary_table_manager"
+
+
+class ObservationResult(StrEnum):
+    PROXY = "proxy"
+    PREVIEW = "preview"
+    PYTHON = "python"
+    DATAFRAME = "dataframe"
+
+
+class SelectionKind(StrEnum):
+    SLICE = "slice"
+    TABLE_ROWS = "table_rows"
+    FIELDS = "fields"
+    KEYS = "keys"
+
+
+def _identifier(value: object, *, name: str) -> str:
+    if not isinstance(value, str) or not value or len(value) > 256:
+        raise ValueError(f"{name} must be a bounded identifier")
+    if not value.isidentifier():
+        raise ValueError(f"{name} must be an identifier without expressions")
+    return value
+
+
+def _qualified_binding(value: object) -> str:
+    if not isinstance(value, str) or len(value) > 512:
+        raise ValueError("context binding must be bounded")
+    parts = value.split(".")
+    if len(parts) != 2 or parts[0].casefold() not in {"bsl", "python"}:
+        raise ValueError("context binding requires bsl. or python. namespace")
+    _identifier(parts[1], name="context binding")
+    return value
+
+
+def _opaque_id(value: object, *, name: str) -> str:
+    if (
+        not isinstance(value, str)
+        or not value
+        or len(value) > 128
+        or any(not (character.isascii() and (character.isalnum() or character in "-_")) for character in value)
+    ):
+        raise ValueError(f"{name} must be an opaque identifier")
+    return value
+
+
+def _sequence(value: object, *, name: str) -> tuple[str, ...]:
+    if isinstance(value, str) or not isinstance(value, Sequence):
+        raise TypeError(f"{name} must be a sequence")
+    result = tuple(_identifier(item, name=name) for item in value)
+    if len(result) > MAX_COLUMNS or len(set(item.casefold() for item in result)) != len(result):
+        raise ValueError(f"{name} must be unique and bounded")
+    return result
+
+
+@dataclass(frozen=True, slots=True)
+class ManagerOrigin:
+    namespace: str
+    root: str
+    fields: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.namespace not in {"frame", "context"}:
+            raise ValueError("manager namespace must be frame or context")
+        _identifier(self.root, name="manager root")
+        fields = _sequence(self.fields, name="manager fields")
+        object.__setattr__(self, "fields", fields)
+
+    @classmethod
+    def from_wire(cls, value: object) -> "ManagerOrigin":
+        if not isinstance(value, Mapping) or set(value) != {"namespace", "root", "fields"}:
+            raise ValueError("manager origin requires namespace, root and fields")
+        return cls(
+            namespace=value["namespace"],  # type: ignore[arg-type]
+            root=value["root"],  # type: ignore[arg-type]
+            fields=value["fields"],  # type: ignore[arg-type]
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ObservationSource:
+    kind: ObservationSourceKind
+    name: str | None = None
+    table: str | None = None
+    manager_id: str | None = None
+    origin: ManagerOrigin | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.kind, ObservationSourceKind):
+            raise TypeError("source kind is invalid")
+        if self.kind is ObservationSourceKind.CONTEXT_BINDING:
+            object.__setattr__(self, "name", _qualified_binding(self.name))
+            if self.table is not None or self.manager_id is not None or self.origin is not None:
+                raise ValueError("context binding cannot include manager fields")
+        elif self.kind is ObservationSourceKind.FRAME_LOCAL:
+            object.__setattr__(self, "name", _identifier(self.name, name="frame local"))
+            if self.table is not None or self.manager_id is not None or self.origin is not None:
+                raise ValueError("frame local cannot include manager fields")
+        elif self.kind is ObservationSourceKind.TEMPORARY_TABLE:
+            if self.name is not None:
+                raise ValueError("temporary table uses table, not name")
+            object.__setattr__(self, "table", _identifier(self.table, name="temporary table"))
+            object.__setattr__(self, "manager_id", _opaque_id(self.manager_id, name="manager_id"))
+            if self.origin is not None:
+                raise ValueError("temporary table uses manager_id, not origin")
+        else:
+            if self.name is not None or self.table is not None or self.manager_id is not None or not isinstance(self.origin, ManagerOrigin):
+                raise ValueError("manager source requires only structured origin")
+
+    @classmethod
+    def from_wire(cls, value: object) -> "ObservationSource":
+        if not isinstance(value, Mapping) or "kind" not in value:
+            raise TypeError("observation source must be a mapping")
+        allowed = {"kind", "name", "table", "manager_id", "origin"}
+        if set(value) - allowed:
+            raise ValueError("unsupported observation source field")
+        try:
+            kind = ObservationSourceKind(value["kind"])
+        except (TypeError, ValueError) as error:
+            raise ValueError("unknown observation source kind") from error
+        origin_value = value.get("origin")
+        return cls(
+            kind=kind,
+            name=value.get("name"),  # type: ignore[arg-type]
+            table=value.get("table"),  # type: ignore[arg-type]
+            manager_id=value.get("manager_id"),  # type: ignore[arg-type]
+            origin=None if origin_value is None else ManagerOrigin.from_wire(origin_value),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ValueSelection:
+    kind: SelectionKind
+    offset: int = 0
+    limit: int | None = None
+    columns: tuple[str, ...] = ()
+    names: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.kind, SelectionKind):
+            raise TypeError("selection kind is invalid")
+        if type(self.offset) is not int or self.offset < 0:
+            raise ValueError("selection offset must be non-negative")
+        if self.limit is not None and (
+            type(self.limit) is not int
+            or self.limit <= 0
+            or self.limit > MAX_SELECTION_LIMIT
+        ):
+            raise ValueError("selection limit must be positive and bounded")
+        columns = _sequence(self.columns, name="columns")
+        names = _sequence(self.names, name="names")
+        object.__setattr__(self, "columns", columns)
+        object.__setattr__(self, "names", names)
+        if self.kind in {SelectionKind.SLICE, SelectionKind.TABLE_ROWS} and self.limit is None:
+            raise ValueError("row and slice selections require a limit")
+        if self.kind is SelectionKind.SLICE and (columns or names):
+            raise ValueError("slice does not accept fields")
+        if self.kind is SelectionKind.TABLE_ROWS and names:
+            raise ValueError("table rows use columns")
+        if self.kind in {SelectionKind.FIELDS, SelectionKind.KEYS} and (
+            self.limit is not None or self.offset != 0 or columns or not names
+        ):
+            raise ValueError("field/key selection requires names only")
+
+    @classmethod
+    def from_wire(cls, value: object) -> "ValueSelection":
+        if not isinstance(value, Mapping) or "kind" not in value:
+            raise TypeError("selection must be a mapping")
+        if set(value) - {"kind", "offset", "limit", "columns", "names"}:
+            raise ValueError("unsupported selection field")
+        try:
+            kind = SelectionKind(value["kind"])
+        except (TypeError, ValueError) as error:
+            raise ValueError("unknown selection kind") from error
+        return cls(
+            kind,
+            offset=value.get("offset", 0),  # type: ignore[arg-type]
+            limit=value.get("limit"),  # type: ignore[arg-type]
+            columns=value.get("columns", ()),  # type: ignore[arg-type]
+            names=value.get("names", ()),  # type: ignore[arg-type]
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ObservationItem:
+    alias: str
+    source: ObservationSource
+    result: ObservationResult = ObservationResult.PROXY
+    select: ValueSelection | None = None
+
+    def __post_init__(self) -> None:
+        _identifier(self.alias, name="observation alias")
+        if not isinstance(self.source, ObservationSource):
+            raise TypeError("observation source is invalid")
+        if not isinstance(self.result, ObservationResult):
+            raise TypeError("observation result is invalid")
+        if self.select is not None and not isinstance(self.select, ValueSelection):
+            raise TypeError("observation selection is invalid")
+
+    @classmethod
+    def from_wire(cls, value: object) -> "ObservationItem":
+        if not isinstance(value, Mapping) or set(value) - {"alias", "source", "result", "select"}:
+            raise ValueError("observation item has unsupported fields")
+        try:
+            result = ObservationResult(value.get("result", ObservationResult.PROXY.value))
+        except (TypeError, ValueError) as error:
+            raise ValueError("unknown observation result") from error
+        selection = value.get("select")
+        return cls(
+            alias=value.get("alias"),  # type: ignore[arg-type]
+            source=ObservationSource.from_wire(value.get("source")),
+            result=result,
+            select=None if selection is None else ValueSelection.from_wire(selection),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ObservationPlan:
+    items: tuple[ObservationItem, ...]
+    budget_profile: str = "agent_metadata"
+
+    def __post_init__(self) -> None:
+        if isinstance(self.items, str) or not isinstance(self.items, Sequence):
+            raise TypeError("observation items must be a sequence")
+        items = tuple(self.items)
+        if len(items) > MAX_OBSERVATIONS or any(not isinstance(item, ObservationItem) for item in items):
+            raise ValueError("observation items must be bounded")
+        aliases = tuple(item.alias.casefold() for item in items)
+        if len(set(aliases)) != len(aliases):
+            raise ValueError("observation aliases must be unique")
+        if self.budget_profile not in {"agent_metadata", "agent_preview", "agent_dataframe"}:
+            raise ValueError("unknown observation budget profile")
+        object.__setattr__(self, "items", items)
+
+    @classmethod
+    def from_wire(cls, value: object) -> "ObservationPlan":
+        if not isinstance(value, Mapping) or set(value) - {"items", "budget_profile"}:
+            raise ValueError("observation plan has unsupported fields")
+        raw_items = value.get("items", ())
+        if isinstance(raw_items, str) or not isinstance(raw_items, Sequence):
+            raise TypeError("observation items must be a sequence")
+        return cls(
+            tuple(ObservationItem.from_wire(item) for item in raw_items),
+            budget_profile=value.get("budget_profile", "agent_metadata"),  # type: ignore[arg-type]
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ObservationFailure:
+    alias: str
+    stage: str
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class ObservationOutcome:
+    outputs: tuple[tuple[str, str], ...] = ()
+    failures: tuple[ObservationFailure, ...] = ()
+
+
+OBSERVATION_WIRE_DATACLASSES: tuple[type[object], ...] = (
+    ManagerOrigin,
+    ObservationSource,
+    ValueSelection,
+    ObservationItem,
+    ObservationPlan,
+    ObservationFailure,
+    ObservationOutcome,
+)