tigrbl-kernel 0.4.2.dev4__py3-none-any.whl → 0.4.3.dev4__py3-none-any.whl

tigrbl_kernel/__init__.py

@@ -3,19 +3,6 @@ from __future__ import annotations
 from importlib import import_module
 from typing import Any, Dict, List, Mapping
 
-try:  # pragma: no cover - additive optional integration
-    _runtime_rust = import_module("tigrbl_runtime.rust")
-    ExecutionBackend = _runtime_rust.ExecutionBackend
-    RustBackendConfig = _runtime_rust.RustBackendConfig
-except Exception:  # pragma: no cover
-    ExecutionBackend = RustBackendConfig = None
-
-from .rust_compile import (
-    build_rust_kernel,
-    build_rust_parity_snapshot,
-    normalize_rust_spec,
-)
-from .rust_plan import RustPlan
 from .measure import (
     build_packed_kernel_measurement_view,
     load_packed_kernel_hot_block,
@@ -80,18 +67,13 @@ def plan_labels(model: type, alias: str) -> list[str]:
 
 
 __all__ = [
-    "ExecutionBackend",
     "Kernel",
-    "RustBackendConfig",
-    "RustPlan",
     "BatchOpPlan",
     "OpView",
     "PackedKernel",
     "SchemaIn",
     "SchemaOut",
     "build_kernel_plan",
-    "build_rust_kernel",
-    "build_rust_parity_snapshot",
     "build_packed_kernel",
     "build_packed_kernel_measurement_view",
     "get_cached_specs",
@@ -99,9 +81,9 @@ __all__ = [
     "load_packed_kernel_hot_block",
     "load_packed_kernel_hot_sections",
     "measure_packed_kernel",
-    "normalize_rust_spec",
     "packed_kernel_measurement",
     "plan_labels",
+    "protocol_streams",
     "serialize_packed_kernel_measurement_view",
     "segment_fusion",
     "transport_atoms",

tigrbl_kernel/_build.py

@@ -15,7 +15,7 @@ from tigrbl_atoms.atoms.sys.phase_db import run as _bind_phase_db
 from tigrbl_atoms.phases import phase_info
 from tigrbl_atoms.types import EdgeTarget, PhaseTreeEdge, PhaseTreeNode, error_phase_for
 from tigrbl_core.config.resolver import resolve_cfg
-from tigrbl_typing.phases import normalize_phase
+from tigrbl_typing.phases import canonicalize_phase_input as normalize_phase
 
 from . import events as _ev
 from .atoms import (

tigrbl_kernel/_compile.py

@@ -1,10 +1,14 @@
 from __future__ import annotations
 
 from dataclasses import replace
+from types import SimpleNamespace
 from typing import Any, Mapping
 
 from tigrbl_atoms import StepFn
+from tigrbl_core._spec.binding_spec import HttpRestBindingSpec
 from tigrbl_core.config.constants import __JSONRPC_DEFAULT_ENDPOINT__
+from tigrbl_core._spec.op_spec import OpSpec
+from tigrbl_core._spec.well_known_spec import well_known_op_alias
 
 from . import events as _ev
 from .models import KernelPlan, OpKey, OpMeta, OpView
@@ -24,6 +28,101 @@ from .utils import (
 DEFAULT_PHASE_ORDER = tuple(getattr(_ev, "PHASES", ())) or _DEFAULT_PHASE_ORDER
 
 
+def _pathspec_iter(app: Any) -> tuple[Any, ...]:
+    collected: list[Any] = []
+    collected.extend(tuple(getattr(app, "_tigrbl_path_specs", ()) or ()))
+    routers = getattr(app, "routers", None)
+    if isinstance(routers, Mapping):
+        router_values = tuple(routers.values())
+    elif isinstance(routers, (list, tuple)):
+        router_values = tuple(routers)
+    else:
+        router_values = ()
+    for router in router_values:
+        collected.extend(tuple(getattr(router, "_tigrbl_path_specs", ()) or ()))
+
+    seen: set[tuple[str, str, str]] = set()
+    deduped: list[Any] = []
+    for path in collected:
+        resource = getattr(path, "well_known", None)
+        key = (
+            str(getattr(path, "kind", "")),
+            str(getattr(path, "path", "")),
+            str(getattr(resource, "name", "")),
+        )
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(path)
+    return tuple(deduped)
+
+
+def _well_known_path_model(app: Any) -> type | None:
+    pathspecs = tuple(
+        path
+        for path in _pathspec_iter(app)
+        if getattr(path, "kind", None) == "well-known"
+        and getattr(path, "well_known", None) is not None
+    )
+    if not pathspecs:
+        return None
+
+    ops: list[Any] = []
+    resources: dict[str, dict[str, Any]] = {}
+    for path in pathspecs:
+        resource = path.well_known
+        alias = well_known_op_alias(resource.name)
+        resources[alias] = {
+            "name": resource.name,
+            "payload": resource.payload,
+            "media_type": resource.media_type,
+            "status_code": resource.status_code,
+            "headers": dict(resource.headers or {}),
+        }
+        ops.append(
+            OpSpec(
+                alias=alias,
+                target="well_known",
+                arity="collection",
+                persist="skip",
+                expose_routes=False,
+                expose_rpc=False,
+                bindings=(
+                    HttpRestBindingSpec(
+                        proto="http.rest",
+                        path=str(path.path),
+                        methods=("GET",),
+                    ),
+                ),
+                status_code=resource.status_code,
+                exchange="request_response",
+                tx_scope="none",
+            )
+        )
+
+    ops_tuple = tuple(ops)
+    model = type("TigrblWellKnownPathOps", (), {})
+    model.resource_name = "well_known"
+    model.__tigrbl_well_known_resources__ = resources
+    model.__tigrbl_ops__ = ops_tuple
+    model.ops = SimpleNamespace(
+        all=ops_tuple,
+        by_alias={op.alias: (op,) for op in ops_tuple},
+        by_key={(op.alias, op.target): op for op in ops_tuple},
+    )
+    model.opspecs = model.ops
+    setattr(app, "_tigrbl_kernel_well_known_model", model)
+    return model
+
+
+def _compile_models(app: Any) -> tuple[Any, ...]:
+    models = list(_table_iter(app))
+    well_known_model = _well_known_path_model(app)
+    if well_known_model is not None:
+        models.append(well_known_model)
+    return tuple(models)
+
+
 def _compile_opview_from_specs(self: Any, specs: Mapping[str, Any], sp: Any) -> OpView:
     return compile_opview_from_specs(specs, sp)
 
@@ -50,7 +149,7 @@ def _compile_plan(self: Any, app: Any) -> KernelPlan:
     egress_chain = self._build_egress(app)
     phases, mainline_phases, error_phases = _phase_info_map(DEFAULT_PHASE_ORDER)
 
-    for model in _table_iter(app):
+    for model in _compile_models(app):
         for sp in _opspecs(model):
             meta_index = len(opmeta)
             target = (getattr(sp, "target", sp.alias) or sp.alias).lower()

tigrbl_kernel/channel_taxonomy.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from tigrbl_core._spec.hook_spec import matches_hook_selector
+
+from .webtransport_events import validate_webtransport_event_payload
+
+WEBTRANSPORT_SUBEVENTS = {
+    "webtransport.connect": "session.open",
+    "webtransport.accept": "session.accept",
+    "webtransport.disconnect": "session.close",
+    "webtransport.close": "session.close",
+    "webtransport.stream.receive": "stream.chunk.received",
+    "webtransport.stream.send": "stream.chunk.emit",
+    "webtransport.stream.close": "stream.close",
+    "webtransport.stream.reset": "stream.close",
+    "webtransport.stream.stop_sending": "stream.close",
+    "webtransport.datagram.receive": "datagram.received",
+    "webtransport.datagram.send": "datagram.emit",
+}
+
+
+def normalize_exchange(exchange: str | None) -> str:
+    token = str(exchange or "request_response")
+    if token == "bidirectional":
+        return "bidirectional_stream"
+    return token
+
+
+def channel_family(scope_type: str, exchange: str) -> str:
+    exchange = normalize_exchange(exchange)
+    if scope_type == "websocket":
+        return "socket"
+    if scope_type == "webtransport":
+        return "session"
+    if exchange in {"server_stream", "client_stream", "bidirectional_stream"}:
+        return "stream"
+    if exchange == "fire_and_forget":
+        return "request"
+    return "response"
+
+
+def channel_kind(scope_type: str, exchange: str) -> str:
+    exchange = normalize_exchange(exchange)
+    if scope_type == "websocket":
+        return "websocket"
+    if scope_type == "webtransport":
+        return "webtransport"
+    if exchange in {"server_stream", "client_stream", "bidirectional_stream"}:
+        return "stream"
+    if exchange == "event_stream":
+        return "sse"
+    return "http"
+
+
+def channel_subevents(scope_type: str, exchange: str) -> tuple[str, ...]:
+    exchange = normalize_exchange(exchange)
+    if scope_type in {"websocket", "webtransport"}:
+        return ("connect", "receive", "emit", "complete", "disconnect")
+    if exchange in {"server_stream", "client_stream", "bidirectional_stream", "event_stream"}:
+        return ("receive", "emit", "complete")
+    return ("receive", "emit", "complete")
+
+
+def webtransport_event_metadata(
+    *,
+    direction: str,
+    message: Mapping[str, Any],
+) -> dict[str, Any]:
+    event_type = str(message.get("type") or "")
+    metadata: dict[str, Any] = {
+        "binding": "webtransport",
+        "event_type": event_type,
+        "type": event_type,
+        "subevent": WEBTRANSPORT_SUBEVENTS.get(event_type, event_type),
+        "framing": message.get("framing"),
+    }
+    try:
+        projection = validate_webtransport_event_payload(
+            event=event_type,
+            channel=direction,
+            payload=dict(message),
+        )
+    except ValueError:
+        projection = {}
+    for key in (
+        "family",
+        "lane",
+        "exchange",
+        "stream_initiator",
+        "stream_direction",
+        "direction",
+        "lane_id",
+        "stream_ordinal",
+        "stream_id_width",
+    ):
+        if projection.get(key) is not None:
+            metadata[key] = projection[key]
+    if "family" not in metadata:
+        if ".stream." in event_type:
+            metadata["family"] = "stream"
+        elif ".datagram." in event_type:
+            metadata["family"] = "datagram"
+        else:
+            metadata["family"] = "session"
+    if "lane" not in metadata:
+        metadata["lane"] = metadata["family"]
+    if "exchange" not in metadata:
+        metadata["exchange"] = "request_response"
+    return metadata
+
+
+def select_webtransport_hooks(
+    hooks: Iterable[Any],
+    *,
+    direction: str,
+    metadata: Mapping[str, Any],
+) -> tuple[Any, ...]:
+    allowed_phases = (
+        {"PRE_HANDLER", "HANDLER"}
+        if direction == "receive"
+        else {"POST_HANDLER", "POST_RESPONSE"}
+    )
+    return tuple(
+        hook
+        for hook in hooks
+        if str(getattr(hook.phase, "value", hook.phase)) in allowed_phases
+        if matches_hook_selector(hook, metadata)
+    )
+
+
+__all__ = [
+    "WEBTRANSPORT_SUBEVENTS",
+    "channel_family",
+    "channel_kind",
+    "channel_subevents",
+    "normalize_exchange",
+    "select_webtransport_hooks",
+    "webtransport_event_metadata",
+]

tigrbl_kernel/cross_transport.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import Any
+
+from tigrbl_kernel.protocol_bindings import compile_binding_protocol_plan
+
+
+TRANSPORT_ENVELOPE_KEYS = frozenset(
+    {
+        "headers",
+        "http_status",
+        "jsonrpc_id",
+        "jsonrpc_version",
+        "path",
+        "rpc_method",
+        "stream_id",
+        "transport",
+        "ws_opcode",
+    }
+)
+
+
+@dataclass(frozen=True)
+class EquivalenceCase:
+    op_id: str
+    category: str
+    bindings: tuple[Mapping[str, Any], ...]
+
+
+def canonical_operation_id(op_id: str) -> str:
+    normalized = str(op_id).strip()
+    if not normalized or "." not in normalized:
+        raise ValueError("canonical operation id must be a non-empty table.operation token")
+    table, op = normalized.split(".", maxsplit=1)
+    if not table or not op:
+        raise ValueError("canonical operation id requires table and operation components")
+    return f"{table}.{op}"
+
+
+def compile_equivalence_manifest(
+    op_id: str,
+    bindings: Iterable[Mapping[str, Any]],
+    *,
+    schema_identity: str = "schema:v1",
+    runtime_plan_identity: str = "runtime-plan:v1",
+) -> dict[str, Any]:
+    canonical_id = canonical_operation_id(op_id)
+    plans = tuple(compile_binding_protocol_plan(canonical_id, binding) for binding in bindings)
+    if not plans:
+        raise ValueError("at least one transport binding is required")
+    return {
+        "op_id": canonical_id,
+        "schema_identity": str(schema_identity),
+        "runtime_plan_identity": str(runtime_plan_identity),
+        "bindings": tuple(_plan_fingerprint(plan) for plan in plans),
+    }
+
+
+def normalized_transport_result(result: Mapping[str, Any]) -> dict[str, Any]:
+    semantic = {
+        key: _freeze(value)
+        for key, value in result.items()
+        if key not in TRANSPORT_ENVELOPE_KEYS
+    }
+    if "diagnostics" in semantic and isinstance(semantic["diagnostics"], Mapping):
+        diagnostics = dict(semantic["diagnostics"])
+        diagnostics.pop("trace_id", None)
+        diagnostics.pop("qlog_id", None)
+        semantic["diagnostics"] = _freeze(diagnostics)
+    return dict(sorted(semantic.items()))
+
+
+def equivalent_transport_results(*results: Mapping[str, Any]) -> bool:
+    if not results:
+        raise ValueError("at least one transport result is required")
+    first = normalized_transport_result(results[0])
+    return all(normalized_transport_result(result) == first for result in results[1:])
+
+
+def equivalent_binding_group(op_id: str, bindings: Iterable[Mapping[str, Any]]) -> bool:
+    manifest = compile_equivalence_manifest(op_id, bindings)
+    families = {binding["family"] for binding in manifest["bindings"]}
+    return bool(families) and len({manifest["op_id"]}) == 1
+
+
+def standard_equivalence_corpus() -> tuple[EquivalenceCase, ...]:
+    return (
+        EquivalenceCase(
+            "Item.read",
+            "standard",
+            (
+                {"kind": "http.rest", "path": "/items/{id}", "methods": ("GET",)},
+                {"kind": "http.jsonrpc", "rpc_method": "Item.read"},
+                {"kind": "ws", "path": "/socket", "framing": "jsonrpc", "subprotocols": ("jsonrpc",)},
+            ),
+        ),
+        EquivalenceCase(
+            "Item.bulk_create",
+            "bulk",
+            (
+                {"kind": "http.rest", "path": "/items/bulk", "methods": ("POST",)},
+                {"kind": "http.jsonrpc", "rpc_method": "Item.bulk_create"},
+            ),
+        ),
+        EquivalenceCase(
+            "Item.search",
+            "query",
+            (
+                {"kind": "http.rest", "path": "/items", "methods": ("GET",)},
+                {"kind": "http.jsonrpc", "rpc_method": "Item.search"},
+            ),
+        ),
+        EquivalenceCase(
+            "Item.tail",
+            "stream",
+            (
+                {"kind": "http.stream", "path": "/items/tail"},
+                {"kind": "http.sse", "path": "/items/events"},
+                {"kind": "webtransport", "profile": "bidi_stream"},
+            ),
+        ),
+        EquivalenceCase(
+            "Item.custom_action",
+            "custom",
+            (
+                {"kind": "http.jsonrpc", "rpc_method": "Item.custom_action"},
+            ),
+        ),
+    )
+
+
+def _plan_fingerprint(plan: Mapping[str, Any]) -> dict[str, Any]:
+    stable = {
+        "binding_kind": plan["binding_kind"],
+        "family": plan["family"],
+        "framing": plan["framing"],
+        "capability_mask": plan["capability_requirements"]["required_mask"],
+        "lifecycle": tuple(
+            (row["family"], row["subevent"]) for row in plan["lifecycle_rows"]
+        ),
+    }
+    stable["fingerprint"] = sha256(repr(stable).encode("utf-8")).hexdigest()
+    return stable
+
+
+def _freeze(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {key: _freeze(value[key]) for key in sorted(value)}
+    if isinstance(value, list):
+        return tuple(_freeze(item) for item in value)
+    if isinstance(value, tuple):
+        return tuple(_freeze(item) for item in value)
+    return value
+
+
+__all__ = [
+    "EquivalenceCase",
+    "canonical_operation_id",
+    "compile_equivalence_manifest",
+    "equivalent_binding_group",
+    "equivalent_transport_results",
+    "normalized_transport_result",
+    "standard_equivalence_corpus",
+]

tigrbl_kernel/dispatch_taxonomy.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any
+
+_BINDINGS = {
+    "http.rest": ("request_response", "request_response", "request.received"),
+    "http.jsonrpc": ("request_response", "rpc", "rpc.request"),
+    "http.stream": ("server_stream", "stream", "stream.start"),
+    "http.sse": ("server_stream", "event_stream", "message.emit"),
+    "websocket": ("bidirectional_stream", "socket", "message.received"),
+    "ws": ("bidirectional_stream", "socket", "message.received"),
+}
+
+
+def derive_runtime_event(event: dict[str, Any]) -> dict[str, Any]:
+    subevent = event.get("subevent")
+    if isinstance(subevent, str) and "." not in subevent:
+        raise ValueError("subevent must be qualified, for example request.received")
+    binding = str(event.get("binding", ""))
+    try:
+        exchange, family, default_subevent = _BINDINGS[binding]
+    except KeyError as exc:
+        raise ValueError(
+            f"unsupported binding for exchange/subevent dispatch: {binding}"
+        ) from exc
+    return {
+        **event,
+        "binding": binding,
+        "exchange": exchange,
+        "family": family,
+        "subevent": subevent or default_subevent,
+    }
+
+
+def resolve_operation(metadata: dict[str, Any]) -> dict[str, Any]:
+    binding = str(metadata.get("binding", ""))
+    subevent = str(metadata.get("subevent", ""))
+    method = str(metadata.get("method", metadata.get("path", "")))
+    return {
+        "exchange": metadata["exchange"],
+        "family": metadata["family"],
+        "subevent": subevent,
+        "op_code": f"{binding}:{subevent}:{method}".strip(":"),
+    }
+
+
+__all__ = ["derive_runtime_event", "resolve_operation"]

tigrbl_kernel/events.py

@@ -4,3 +4,13 @@ Canonical event anchors and ordering now live in ``tigrbl_atoms.events``.
 """
 
 from tigrbl_atoms.events import *  # noqa: F403
+from tigrbl_atoms.events import __all__ as _ATOM_EVENT_EXPORTS
+from tigrbl_atoms.events import canonicalize_phase
+
+
+def is_error_phase(name: str) -> bool:
+    phase = canonicalize_phase(name)
+    return str(phase).startswith("ON_") or phase == "TX_ROLLBACK"
+
+
+__all__ = [*_ATOM_EVENT_EXPORTS, "is_error_phase"]

tigrbl_kernel/helpers.py

@@ -6,7 +6,7 @@ import logging
 from typing import Any, Iterable, Mapping, Optional, Sequence
 
 from tigrbl_atoms.types import AtomFailure, BaseCtx, FailedCtx, build_error_ctx
-from tigrbl_typing.phases import normalize_phase
+from tigrbl_typing.phases import canonicalize_phase_input
 
 try:
     from tigrbl_kernel import trace as _trace  # type: ignore
@@ -210,7 +210,7 @@ async def _run_chain(ctx: Any, chain: Optional[Iterable[Any]], *, phase: str) ->
 def _g(phases: Optional[Mapping[str, Sequence[Any]]], key: str) -> Sequence[Any]:
     if not phases:
         return ()
-    normalized = normalize_phase(key) or key
+    normalized = canonicalize_phase_input(key) or key
     chain = phases.get(normalized, ())
     if chain:
         return chain

tigrbl_kernel/loop_modes.py

@@ -31,4 +31,22 @@ def select_loop_mode(
     return "dispatch" if handlers else "owner"
 
 
-__all__ = ["select_loop_mode"]
+def build_loop_controller(
+    *,
+    mode: str,
+    binding: str,
+    subevent_handlers: Iterable[str] = (),
+) -> dict[str, object]:
+    if mode not in {"owner", "dispatch"}:
+        raise ValueError(f"unsupported runtime loop mode {mode!r}")
+    handlers = tuple(subevent_handlers or ())
+    return {
+        "mode": mode,
+        "binding": binding,
+        "subevent_handlers": handlers,
+        "dispatches_subevents": mode == "dispatch",
+        "owner_controls_receive": mode == "owner",
+    }
+
+
+__all__ = ["build_loop_controller", "select_loop_mode"]

tigrbl_kernel/measure.py

@@ -6,7 +6,7 @@ import struct
 import zlib
 from typing import Any, Mapping
 
-from tigrbl_typing.phases import normalize_phase
+from tigrbl_typing.phases import canonicalize_phase_input as normalize_phase
 
 from .models import (
     HotOpPlan,

tigrbl_kernel/ordering.py

@@ -57,6 +57,7 @@ _PREF: Dict[str, Tuple[str, ...]] = {
         "sys:handler_bulk_replace",
         "sys:handler_bulk_merge",
         "sys:handler_bulk_delete",
+        "sys:handler_well_known",
         "sys:handler_persistence",
     ),
     _ev.BATCH_RESULT_SLOTS: ("batch:result_slots",),