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

onec_runtime/bootstrap.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import asdict, dataclass
+from time import monotonic
+from typing import Protocol
+from uuid import UUID
+
+from onec_runtime.errors import (
+    CommandTimeout,
+    ExtensionHandshakeError,
+    ProtocolError,
+    UnexpectedStop,
+)
+from onec_runtime.extension_bundle import EXTENSION_NAME, ExtensionHandshakeEvidence
+from onec_runtime.kernel import SESSION_MODULE_PROPERTY_ID
+from onec_runtime.rdbg.models import (
+    DebugTarget,
+    EvaluationResult,
+    ModifyResult,
+    ModuleLocation,
+    StopEvent,
+)
+
+
+class BootstrapSession(Protocol):
+    break_on_next: bool
+
+    def wait_for_any_stop(
+        self,
+        *,
+        timeout_s: float,
+        on_poll: Callable[[], None] | None = None,
+    ) -> StopEvent: ...
+
+    def continue_(self) -> None: ...
+
+
+class ServerBootstrapSession(Protocol):
+    expected_location: ModuleLocation
+    target: DebugTarget | None
+
+    def set_service_breakpoint(self) -> None: ...
+
+    def continue_(self) -> None: ...
+
+    def wait_for_service_stop(self, *, timeout_s: float) -> StopEvent: ...
+
+
+class ServerGuardSession(Protocol):
+    def evaluate(self, expression: str) -> EvaluationResult: ...
+
+    def modify(self, variable: str, value_expression: str) -> ModifyResult: ...
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionHandshakeContract:
+    product_id: str
+    artifact_version: str
+    protocol_version: str
+
+
+_HANDSHAKE_EXPRESSIONS = (
+    ("product_id", "ИдентификаторПродуктаRuntime"),
+    ("artifact_version", "ВерсияАртефактаRuntime"),
+    ("protocol_version", "ВерсияПротоколаRuntime"),
+)
+_MAX_HANDSHAKE_VALUE_LENGTH = 128
+
+
+def _handshake_string(result: EvaluationResult, variable: str) -> str:
+    if result.error_occurred:
+        raise ExtensionHandshakeError(
+            f"Extension handshake evaluation failed for {variable}"
+        )
+    if result.type_name != "Строка":
+        raise ExtensionHandshakeError(
+            f"Extension handshake variable {variable} is not a string"
+        )
+    presentation = result.presentation
+    if (
+        not presentation
+        or len(presentation) > _MAX_HANDSHAKE_VALUE_LENGTH
+        or any(ord(character) < 32 for character in presentation)
+    ):
+        raise ExtensionHandshakeError(
+            f"Extension handshake variable {variable} has an unsafe value"
+        )
+    if presentation.startswith('"') or presentation.endswith('"'):
+        if not (presentation.startswith('"') and presentation.endswith('"')):
+            raise ExtensionHandshakeError(
+                f"Extension handshake variable {variable} has an invalid presentation"
+            )
+        inner = presentation[1:-1]
+        if '"' in inner.replace('""', ""):
+            raise ExtensionHandshakeError(
+                f"Extension handshake variable {variable} has an invalid presentation"
+            )
+        presentation = inner.replace('""', '"')
+    if not presentation:
+        raise ExtensionHandshakeError(
+            f"Extension handshake variable {variable} has an empty value"
+        )
+    if len(presentation) > _MAX_HANDSHAKE_VALUE_LENGTH:
+        raise ExtensionHandshakeError(
+            f"Extension handshake variable {variable} has an unsafe value"
+        )
+    return presentation
+
+
+def observe_extension_handshake(
+    session: ServerGuardSession,
+    *,
+    target_type: str,
+    location: ModuleLocation,
+) -> ExtensionHandshakeEvidence:
+    values = {
+        field: _handshake_string(session.evaluate(variable), variable)
+        for field, variable in _HANDSHAKE_EXPRESSIONS
+    }
+    return ExtensionHandshakeEvidence(
+        target_type=target_type,
+        product_id=values["product_id"],
+        artifact_version=values["artifact_version"],
+        protocol_version=values["protocol_version"],
+        location=location,
+    )
+
+
+def verify_extension_handshake(
+    session: ServerGuardSession,
+    contract: ExtensionHandshakeContract,
+    *,
+    target_type: str,
+    location: ModuleLocation,
+) -> ExtensionHandshakeEvidence:
+    evidence = observe_extension_handshake(
+        session,
+        target_type=target_type,
+        location=location,
+    )
+    expected = (
+        ("ИдентификаторПродуктаRuntime", evidence.product_id, contract.product_id),
+        ("ВерсияАртефактаRuntime", evidence.artifact_version, contract.artifact_version),
+        ("ВерсияПротоколаRuntime", evidence.protocol_version, contract.protocol_version),
+    )
+    for variable, actual, required in expected:
+        if actual != required:
+            raise ExtensionHandshakeError(
+                f"Extension handshake mismatch for {variable}"
+            )
+    return evidence
+
+
+def verify_extension_safe_mode_disabled(session: ServerGuardSession) -> None:
+    """Verify the installed extension property in the live server infobase."""
+    expression = (
+        'РасширенияКонфигурации.Получить(Новый Структура("Имя", '
+        f'"{EXTENSION_NAME}"))[0].БезопасныйРежим'
+    )
+    result = session.evaluate(expression)
+    if (
+        result.error_occurred
+        or result.type_name not in {"Булево", "Boolean"}
+        or result.presentation not in {"Ложь", "False"}
+    ):
+        raise ExtensionHandshakeError(
+            "Runtime extension safe mode is enabled or could not be verified"
+        )
+
+
+@dataclass(frozen=True)
+class GuardValueEvidence:
+    type_name: str
+    presentation: str
+    error_occurred: bool
+
+
+@dataclass(frozen=True)
+class ServerLoopGuardEvidence:
+    variable: str
+    before: GuardValueEvidence
+    write: GuardValueEvidence
+    after: GuardValueEvidence
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "variable": self.variable,
+            "before": asdict(self.before),
+            "write": {"expression": "Истина", **asdict(self.write)},
+            "after": asdict(self.after),
+        }
+
+
+def _guard_value(result: EvaluationResult | ModifyResult) -> GuardValueEvidence:
+    return GuardValueEvidence(
+        type_name=result.type_name,
+        presentation=result.presentation,
+        error_occurred=result.error_occurred,
+    )
+
+
+def _is_boolean(result: EvaluationResult | ModifyResult, presentation: str) -> bool:
+    return (
+        not result.error_occurred
+        and result.type_name == "Булево"
+        and result.presentation == presentation
+    )
+
+
+def enable_server_kernel_loop(
+    session: ServerGuardSession,
+) -> ServerLoopGuardEvidence:
+    variable = "ПродолжатьЦикл"
+    before = session.evaluate(variable)
+    if not _is_boolean(before, "Ложь"):
+        raise ProtocolError("Server KernelLoop guard was not Ложь before bootstrap")
+    write = session.modify(variable, "Истина")
+    if not _is_boolean(write, "Истина"):
+        detail = f": {write.error_text}" if write.error_text else ""
+        raise ProtocolError(f"Unable to enable server KernelLoop guard{detail}")
+    after = session.evaluate(variable)
+    if not _is_boolean(after, "Истина"):
+        raise ProtocolError("Server KernelLoop guard readback was not Истина")
+    return ServerLoopGuardEvidence(
+        variable=variable,
+        before=_guard_value(before),
+        write=_guard_value(write),
+        after=_guard_value(after),
+    )
+
+
+def _is_known_break_on_next_transient(
+    session: BootstrapSession,
+    location: ModuleLocation,
+    expected: ModuleLocation,
+) -> bool:
+    if not session.break_on_next:
+        return False
+    return bool(
+        (
+            location.module_type == "ConfigModule"
+            and location.property_id == UUID(SESSION_MODULE_PROPERTY_ID)
+            and location.line > 0
+        )
+        or (
+            location.module_type == expected.module_type
+            and location.url == expected.url
+            and location.object_id == expected.object_id
+            and location.property_id == expected.property_id
+            and location.extension_name == expected.extension_name
+            and location.ext_id == expected.ext_id
+            and 0 < location.line < expected.line
+        )
+    )
+
+
+def wait_for_managed_startup_stop(
+    session: BootstrapSession,
+    expected: ModuleLocation,
+    *,
+    timeout_s: float,
+    on_poll: Callable[[], None] | None = None,
+) -> StopEvent:
+    deadline = monotonic() + timeout_s
+    while monotonic() < deadline:
+        remaining = max(0.1, deadline - monotonic())
+        if on_poll is None:
+            stop = session.wait_for_any_stop(timeout_s=remaining)
+        else:
+            stop = session.wait_for_any_stop(timeout_s=remaining, on_poll=on_poll)
+        if stop.location == expected:
+            return stop
+        if _is_known_break_on_next_transient(session, stop.location, expected):
+            session.continue_()
+            continue
+        raise UnexpectedStop(f"Unexpected managed bootstrap stop: {stop.location!r}")
+    raise CommandTimeout("Timed out waiting for managed startup breakpoint")
+
+
+def wait_for_server_entry_then_service(
+    session: ServerBootstrapSession,
+    entry_location: ModuleLocation,
+    service_location: ModuleLocation,
+    *,
+    timeout_s: float,
+    on_entry: Callable[[ServerBootstrapSession], None] | None = None,
+    server_target_type: str = "ServerEmulation",
+) -> tuple[StopEvent, StopEvent]:
+    deadline = monotonic() + timeout_s
+
+    def remaining() -> float:
+        return max(0.1, deadline - monotonic())
+
+    session.expected_location = entry_location
+    session.set_service_breakpoint()
+    session.continue_()
+    entry_stop = session.wait_for_service_stop(timeout_s=remaining())
+    if session.target is None or session.target.target_type != server_target_type:
+        raise ProtocolError(f"Runtime server entry did not stop on {server_target_type}")
+    if on_entry is not None:
+        on_entry(session)
+
+    session.expected_location = service_location
+    session.set_service_breakpoint()
+    session.continue_()
+    service_stop = session.wait_for_service_stop(timeout_s=remaining())
+    if session.target is None or session.target.target_type != server_target_type:
+        raise ProtocolError(f"Runtime service loop did not stop on {server_target_type}")
+    return entry_stop, service_stop

onec_runtime/breakpoint_workspace.py

@@ -0,0 +1,249 @@
+"""Single-owner, full-replacement RDBG breakpoint workspace."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+import json
+from threading import RLock
+from typing import Protocol
+
+from onec_runtime.errors import ProtocolError
+from onec_runtime.rdbg.models import ModuleLocation
+
+
+class BreakpointWorkspaceOutcomeUnknown(ProtocolError):
+    """The debugger may have applied a workspace whose receipt was not observed."""
+
+
+class _BreakpointSession(Protocol):
+    def set_breakpoints(self, locations: tuple[ModuleLocation, ...]) -> None: ...
+
+
+def _location_key(location: ModuleLocation) -> tuple[object, ...]:
+    return (
+        location.module_type,
+        location.url,
+        location.object_id.hex,
+        location.property_id.hex,
+        location.line,
+        location.extension_name,
+        location.ext_id,
+    )
+
+
+def _location_payload(location: ModuleLocation) -> dict[str, object]:
+    return {
+        "module_type": location.module_type,
+        "url": location.url,
+        "object_id": str(location.object_id),
+        "property_id": str(location.property_id),
+        "line": location.line,
+        "extension_name": location.extension_name,
+        "ext_id": location.ext_id,
+    }
+
+
+def _validate_locations(
+    value: tuple[ModuleLocation, ...],
+    group: str,
+) -> None:
+    if (
+        type(value) is not tuple
+        or any(type(location) is not ModuleLocation for location in value)
+        or len(set(value)) != len(value)
+    ):
+        raise ValueError(f"{group} breakpoint locations are invalid")
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class WorkspaceSnapshot:
+    version: int
+    service: ModuleLocation
+    captures: tuple[ModuleLocation, ...]
+    ordinary_users: tuple[ModuleLocation, ...]
+    worker_slots: tuple[ModuleLocation, ...]
+    shielded: bool
+
+    def __post_init__(self) -> None:
+        if type(self.version) is not int or self.version < 0:
+            raise ValueError("breakpoint workspace version is invalid")
+        if type(self.service) is not ModuleLocation:
+            raise ValueError("breakpoint workspace service location is invalid")
+        _validate_locations(self.captures, "capture")
+        _validate_locations(self.ordinary_users, "ordinary user")
+        _validate_locations(self.worker_slots, "Worker")
+        if type(self.shielded) is not bool:
+            raise ValueError("breakpoint workspace shield is invalid")
+        groups = (
+            {self.service},
+            set(self.captures),
+            set(self.ordinary_users),
+            set(self.worker_slots),
+        )
+        for left_index, left in enumerate(groups):
+            for right in groups[left_index + 1 :]:
+                if left & right:
+                    raise ProtocolError("Breakpoint workspace groups overlap")
+
+    @property
+    def effective_locations(self) -> tuple[ModuleLocation, ...]:
+        return (
+            (self.service,)
+            + (() if self.shielded else self.captures)
+            + self.ordinary_users
+            + self.worker_slots
+        )
+
+    @property
+    def digest(self) -> str:
+        payload = json.dumps(
+            [_location_payload(item) for item in self.effective_locations],
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode("utf-8")
+        return sha256(payload).hexdigest()
+
+    def __repr__(self) -> str:
+        return (
+            "WorkspaceSnapshot("
+            f"version={self.version}, service=<redacted>, "
+            f"captures={len(self.captures)}, "
+            f"ordinary_users={len(self.ordinary_users)}, "
+            f"worker_slots={len(self.worker_slots)}, "
+            f"shielded={self.shielded}, digest={self.digest!r})"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class WorkspaceInstallReceipt:
+    version: int
+    requested_digest: str
+
+    def __post_init__(self) -> None:
+        if (
+            type(self.version) is not int
+            or self.version < 0
+            or type(self.requested_digest) is not str
+            or len(self.requested_digest) != 64
+        ):
+            raise ValueError("breakpoint workspace receipt is invalid")
+
+
+class BreakpointWorkspaceController:
+    """Serialize complete debugger workspace replacements and their evidence."""
+
+    __slots__ = (
+        "_confirmed",
+        "_lock",
+        "_prepared",
+        "_session",
+        "_unknown",
+    )
+
+    def __init__(
+        self,
+        session: _BreakpointSession,
+        initial: WorkspaceSnapshot,
+    ) -> None:
+        if type(initial) is not WorkspaceSnapshot:
+            raise TypeError("initial breakpoint workspace is required")
+        self._session = session
+        self._confirmed = initial
+        self._unknown = False
+        self._prepared: dict[int, WorkspaceSnapshot] = {}
+        self._lock = RLock()
+
+    @property
+    def confirmed_snapshot(self) -> WorkspaceSnapshot:
+        with self._lock:
+            return self._confirmed
+
+    def prepare(
+        self,
+        *,
+        captures: tuple[ModuleLocation, ...],
+        ordinary_users: tuple[ModuleLocation, ...],
+        worker_slots: tuple[ModuleLocation, ...],
+        shielded: bool,
+    ) -> WorkspaceSnapshot:
+        if (
+            type(worker_slots) is not tuple
+            or any(type(item) is not ModuleLocation for item in worker_slots)
+        ):
+            raise ValueError("Worker breakpoint locations are invalid")
+        unique_worker_slots = tuple(sorted(set(worker_slots), key=_location_key))
+        with self._lock:
+            self.require_confirmed()
+            snapshot = WorkspaceSnapshot(
+                self._confirmed.version + 1,
+                self._confirmed.service,
+                captures,
+                ordinary_users,
+                unique_worker_slots,
+                shielded,
+            )
+            self._prepared[id(snapshot)] = snapshot
+            return snapshot
+
+    def install(self, snapshot: WorkspaceSnapshot) -> WorkspaceInstallReceipt:
+        if type(snapshot) is not WorkspaceSnapshot:
+            raise TypeError("breakpoint workspace snapshot is required")
+        with self._lock:
+            self.require_confirmed()
+            if (
+                self._prepared.get(id(snapshot)) is not snapshot
+                or snapshot.version != self._confirmed.version + 1
+            ):
+                raise ProtocolError("Breakpoint workspace proposal is stale or foreign")
+            del self._prepared[id(snapshot)]
+            if snapshot.effective_locations != self._confirmed.effective_locations:
+                setter = getattr(self._session, "set_breakpoints", None)
+                if not callable(setter):
+                    raise ProtocolError("Breakpoint workspace session is unavailable")
+                try:
+                    setter(snapshot.effective_locations)
+                except BaseException as error:
+                    self._unknown = True
+                    self._prepared.clear()
+                    raise BreakpointWorkspaceOutcomeUnknown(
+                        "Worker breakpoint workspace outcome is unknown"
+                    ) from error
+            self._confirmed = snapshot
+            self._prepared = {
+                key: value
+                for key, value in self._prepared.items()
+                if value.version > snapshot.version
+            }
+            return WorkspaceInstallReceipt(snapshot.version, snapshot.digest)
+
+    def require_confirmed(self) -> None:
+        with self._lock:
+            if self._unknown:
+                raise BreakpointWorkspaceOutcomeUnknown(
+                    "Worker breakpoint workspace outcome is unknown"
+                )
+
+    def quarantine(self) -> None:
+        with self._lock:
+            self._unknown = True
+            self._prepared.clear()
+
+    def _adopt_confirmed_session(
+        self,
+        session: _BreakpointSession,
+        effective_locations: tuple[ModuleLocation, ...],
+    ) -> None:
+        """Bind a recovered session after it replayed the exact confirmed workspace."""
+        with self._lock:
+            if not callable(getattr(session, "set_breakpoints", None)):
+                raise TypeError("breakpoint workspace session is invalid")
+            if (
+                type(effective_locations) is not tuple
+                or effective_locations != self._confirmed.effective_locations
+            ):
+                raise ProtocolError("Recovered breakpoint workspace does not match")
+            self._session = session
+            self._unknown = False
+            self._prepared.clear()

onec_runtime/bsl/__init__.py

@@ -0,0 +1,139 @@
+"""Minimal Python lexer/parser target used by the BSL grammar spike."""
+
+from onec_runtime.bsl.diagnostics import (
+    DiagnosticCoordinateSpace,
+    DiagnosticStage,
+    LoweredSourceLocation,
+    MappingConfidence,
+    NormalizedDiagnostic,
+    ParsedPlatformDiagnostic,
+    PlatformCoordinateCodec,
+    VisibleSourceContext,
+    VisibleSourceLocation,
+    normalize_source_error,
+    parse_platform_diagnostic,
+    remap_platform_diagnostic,
+)
+from onec_runtime.bsl.preprocessor import preprocess_server_source
+from onec_runtime.bsl.semantic_lowering import (
+    LoweringMode,
+    MethodScope,
+    ModuleBinding,
+    NameBinding,
+    SemanticLoweringError,
+    SemanticLoweringResult,
+    SemanticNotebookLowerer,
+    SourceEdit,
+    WorkerExport,
+)
+from onec_runtime.bsl.source_maps import (
+    LineIndex,
+    MappedSource,
+    MappingRelation,
+    SourceArtifactKind,
+    SourceArtifactRef,
+    SourceMap,
+    SourceSpan,
+    SourceTransformBuilder,
+    SourceUnitKind,
+    SourceUnitRef,
+    mapped_visible_source,
+    source_sha256,
+)
+from onec_runtime.bsl.worker_projection_model import (
+    BareName,
+    BareNameKind,
+    ParsedMethodModel,
+    ParsedModuleModel,
+)
+
+__all__ = [
+    "DiagnosticCoordinateSpace",
+    "DiagnosticStage",
+    "LoweredSourceLocation",
+    "LoweringMode",
+    "MappingConfidence",
+    "MethodScope",
+    "ModuleUniverseAdmissionError",
+    "ModuleBinding",
+    "NameBinding",
+    "NormalizedDiagnostic",
+    "ParsedPlatformDiagnostic",
+    "PlatformCoordinateCodec",
+    "BareName",
+    "BareNameKind",
+    "ParsedMethodModel",
+    "ParsedModuleModel",
+    "SemanticLoweringError",
+    "SemanticLoweringResult",
+    "SemanticNotebookLowerer",
+    "SourceEdit",
+    "WorkerExport",
+    "WorkerModuleUnit",
+    "VisibleSourceContext",
+    "VisibleSourceLocation",
+    "normalize_source_error",
+    "parse_platform_diagnostic",
+    "remap_platform_diagnostic",
+    "preprocess_server_source",
+    "CommonModuleCatalogSnapshot",
+    "CommonModuleDescriptor",
+    "CommonModuleScope",
+    "SessionCommonModuleCatalog",
+    "LineIndex",
+    "MappedSource",
+    "MappingRelation",
+    "SourceArtifactKind",
+    "SourceArtifactRef",
+    "SourceMap",
+    "SourceSpan",
+    "SourceTransformBuilder",
+    "SourceUnitKind",
+    "SourceUnitRef",
+    "mapped_visible_source",
+    "source_sha256",
+    "MODULE_SCOPE_DEPENDENCY",
+    "ResolvedMethodPlan",
+    "ResolvedModulePlan",
+    "resolve_worker_dependencies",
+    "worker_model_candidate_names",
+]
+
+
+def __getattr__(name: str) -> object:
+    if name not in {
+        "CommonModuleCatalogSnapshot",
+        "CommonModuleDescriptor",
+        "CommonModuleScope",
+        "ModuleUniverseAdmissionError",
+        "SessionCommonModuleCatalog",
+        "WorkerModuleUnit",
+        "MODULE_SCOPE_DEPENDENCY",
+        "ResolvedMethodPlan",
+        "ResolvedModulePlan",
+        "resolve_worker_dependencies",
+        "worker_model_candidate_names",
+    }:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    if name in {
+        "CommonModuleCatalogSnapshot",
+        "CommonModuleDescriptor",
+        "CommonModuleScope",
+        "SessionCommonModuleCatalog",
+    }:
+        from onec_runtime.bsl import module_catalog
+
+        return getattr(module_catalog, name)
+    if name in {
+        "MODULE_SCOPE_DEPENDENCY",
+        "ResolvedMethodPlan",
+        "ResolvedModulePlan",
+        "resolve_worker_dependencies",
+        "worker_model_candidate_names",
+    }:
+        from onec_runtime.bsl import worker_dependency_resolver
+
+        return getattr(worker_dependency_resolver, name)
+    from onec_runtime.bsl import module_universe
+
+    return getattr(module_universe, name)