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

tigrbl_kernel/packed_access.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+import zlib
+
+from .models import PackedHotSection, PackedHotSectionDirectory, PackedKernel
+
+HOT_RUNNER_GENERIC = 0
+HOT_RUNNER_LINEAR_DIRECT = 1
+HOT_RUNNER_COMPILED_PARAM = 2
+HOT_RUNNER_WS_UNARY_TEXT = 3
+
+DIRECT_INVOKE_STEP = 0
+DIRECT_INVOKE_RUN = 1
+DIRECT_INVOKE_RUN_WITH_NONE = 2
+DIRECT_INVOKE_RUN_WITH_DEP = 3
+
+TRANSPORT_KIND_GENERIC = 0
+TRANSPORT_KIND_REST = 1
+TRANSPORT_KIND_JSONRPC = 2
+TRANSPORT_KIND_CHANNEL = 3
+
+HTTP_METHOD_ID_BY_NAME = {
+    "GET": 1,
+    "HEAD": 2,
+    "POST": 3,
+    "PUT": 4,
+    "PATCH": 5,
+    "DELETE": 6,
+    "OPTIONS": 7,
+    "TRACE": 8,
+    "CONNECT": 9,
+}
+
+
+def hot_block_view(packed: PackedKernel) -> Mapping[str, Any]:
+    view = getattr(packed, "hot_block_view", None)
+    return view if isinstance(view, Mapping) else {}
+
+
+def hot_block_sections(packed: PackedKernel) -> PackedHotSectionDirectory | None:
+    sections = getattr(packed, "hot_block_sections", None)
+    return sections if isinstance(sections, PackedHotSectionDirectory) else None
+
+
+def hot_section(packed: PackedKernel, key: str) -> PackedHotSection | None:
+    directory = hot_block_sections(packed)
+    if directory is None:
+        return None
+    return directory.get(key)
+
+
+def hot_array(
+    packed: PackedKernel,
+    key: str,
+    fallback: tuple[Any, ...] | tuple[int, ...] | tuple[str, ...],
+) -> tuple[Any, ...]:
+    values = hot_block_view(packed).get(key)
+    if isinstance(values, tuple):
+        return values
+    if isinstance(values, list):
+        return tuple(values)
+    return fallback
+
+
+def hot_int_at(
+    packed: PackedKernel,
+    key: str,
+    index: int,
+    fallback: tuple[int, ...] | tuple[Any, ...],
+) -> int | None:
+    section = hot_section(packed, key)
+    if section is not None:
+        if 0 <= index < int(section.count):
+            return section.get_int(index)
+        return None
+    if 0 <= index < len(fallback):
+        return int(fallback[index])
+    return None
+
+
+def hot_count(
+    packed: PackedKernel,
+    key: str,
+    fallback: tuple[int, ...] | tuple[Any, ...] | tuple[str, ...],
+) -> int:
+    section = hot_section(packed, key)
+    if section is not None:
+        return int(section.count)
+    return len(fallback)
+
+
+def stable_name_hash64(value: str, *, lowercase: bool = False) -> int:
+    normalized = value.lower() if lowercase else value
+    encoded = normalized.encode("utf-8")
+    lo = zlib.crc32(encoded) & 0xFFFFFFFF
+    hi = zlib.crc32(encoded, 0x9E3779B9) & 0xFFFFFFFF
+    return (hi << 32) | lo
+
+
+def http_method_id(method: str) -> int:
+    normalized = str(method or "").upper()
+    cached = HTTP_METHOD_ID_BY_NAME.get(normalized)
+    if cached is not None:
+        return cached
+    return 1024 + (stable_name_hash64(normalized) & 0xFFFF)
+
+
+def coerce_int(value: Any) -> int | None:
+    return value if isinstance(value, int) else None
+
+
+def coerce_dict(value: Any) -> Mapping[str, Any]:
+    return value if isinstance(value, Mapping) else {}
+
+
+def resolve_program_hot_runner_id(
+    packed: PackedKernel,
+    program_id: int,
+    hot_op_plan: Any | None,
+) -> int:
+    if hot_op_plan is not None:
+        program_hot_runner_id = coerce_int(
+            getattr(hot_op_plan, "program_hot_runner_id", None)
+        )
+        if program_hot_runner_id is not None:
+            return program_hot_runner_id
+    fallback = tuple(getattr(packed, "program_hot_runner_ids", ()) or ())
+    value = hot_int_at(packed, "program_hot_runner_ids", program_id, fallback)
+    return int(value) if value is not None else HOT_RUNNER_GENERIC

tigrbl_kernel/packed_selectors.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+
+from .models import KernelPlan, PackedKernel
+from .packed_access import (
+    hot_array,
+    hot_section,
+    http_method_id,
+    stable_name_hash64,
+)
+
+ExactRouteCache = MutableMapping[int, Mapping[int, tuple[int, int]]]
+ExactRouteVerifyCache = MutableMapping[
+    int, Mapping[int, Mapping[int, tuple[tuple[str, int], ...]]]
+]
+ExactWebSocketCache = MutableMapping[int, Mapping[tuple[str, str], int]]
+ExactJsonRpcCache = MutableMapping[int, Mapping[str, Mapping[str, tuple[int, str, str]]]]
+
+
+def resolve_hot_exact_route_slices(
+    packed: PackedKernel,
+    cache: ExactRouteCache,
+) -> Mapping[int, tuple[int, int]]:
+    packed_id = id(packed)
+    cached = cache.get(packed_id)
+    if cached is not None:
+        return cached
+    method_ids = hot_section(packed, "exact_method_ids")
+    path_hashes = hot_section(packed, "exact_path_hashes")
+    program_ids = hot_section(packed, "exact_program_ids")
+    if method_ids is None or path_hashes is None or program_ids is None:
+        cache[packed_id] = {}
+        return {}
+    if not (
+        int(method_ids.count) == int(path_hashes.count) == int(program_ids.count)
+    ):
+        cache[packed_id] = {}
+        return {}
+    directory: dict[int, tuple[int, int]] = {}
+    total = int(method_ids.count)
+    current_method_id = -1
+    current_start = 0
+    current_count = 0
+    for index in range(total):
+        method_id = int(method_ids.get_int(index))
+        if method_id == current_method_id:
+            current_count += 1
+            continue
+        if current_count > 0:
+            directory[current_method_id] = (current_start, current_count)
+        current_method_id = method_id
+        current_start = index
+        current_count = 1
+    if current_count > 0:
+        directory[current_method_id] = (current_start, current_count)
+    frozen = {
+        int(method_id): (int(start), int(count))
+        for method_id, (start, count) in directory.items()
+    }
+    cache[packed_id] = frozen
+    return frozen
+
+
+def resolve_hot_exact_route_verify(
+    packed: PackedKernel,
+    cache: ExactRouteVerifyCache,
+) -> Mapping[int, Mapping[int, tuple[tuple[str, int], ...]]]:
+    packed_id = id(packed)
+    cached = cache.get(packed_id)
+    if cached is not None:
+        return cached
+
+    route = getattr(packed, "rest_exact_route_to_program", None)
+    if not isinstance(route, Mapping):
+        cache[packed_id] = {}
+        return {}
+
+    verify: dict[int, dict[int, list[tuple[str, int]]]] = {}
+    for route_key, program_id in route.items():
+        if (
+            not isinstance(route_key, tuple)
+            or len(route_key) != 2
+            or not isinstance(route_key[0], str)
+            or not isinstance(route_key[1], str)
+            or not isinstance(program_id, int)
+        ):
+            continue
+        method_name, exact_path = route_key
+        method_id = http_method_id(method_name)
+        path_hash = stable_name_hash64(exact_path)
+        method_bucket = verify.setdefault(method_id, {})
+        method_bucket.setdefault(path_hash, []).append((exact_path, program_id))
+
+    frozen = {
+        int(method_id): {
+            int(path_hash): tuple(entries)
+            for path_hash, entries in method_bucket.items()
+        }
+        for method_id, method_bucket in verify.items()
+    }
+    cache[packed_id] = frozen
+    return frozen
+
+
+def resolve_program_id_from_exact_route(
+    packed: PackedKernel,
+    method: str,
+    path: str,
+    route_cache: ExactRouteCache,
+    verify_cache: ExactRouteVerifyCache,
+) -> int:
+    method_id = http_method_id(method)
+    path_hash = stable_name_hash64(path)
+    path_hashes = hot_section(packed, "exact_path_hashes")
+    program_ids = hot_section(packed, "exact_program_ids")
+    method_slices = resolve_hot_exact_route_slices(packed, route_cache)
+    method_slice = method_slices.get(method_id)
+    if (
+        method_slice is not None
+        and path_hashes is not None
+        and program_ids is not None
+        and int(path_hashes.count) == int(program_ids.count)
+    ):
+        start_index, count = method_slice
+        found_index = path_hashes.find_aligned_u64(
+            path_hash,
+            start_index=start_index,
+            count=count,
+        )
+        if start_index <= found_index < start_index + count:
+            program_id = int(program_ids.get_int(found_index))
+            verify = resolve_hot_exact_route_verify(packed, verify_cache)
+            method_verify = verify.get(method_id, {})
+            candidates = method_verify.get(path_hash, ())
+            if candidates:
+                for candidate_path, candidate_program_id in candidates:
+                    if candidate_path == path:
+                        return int(candidate_program_id)
+                return -1
+            return program_id
+    method_ids = hot_array(packed, "exact_method_ids", tuple())
+    path_hash_array = hot_array(packed, "exact_path_hashes", tuple())
+    program_id_array = hot_array(packed, "exact_program_ids", tuple())
+    for candidate_method_id, candidate_hash, program_id in zip(
+        method_ids, path_hash_array, program_id_array
+    ):
+        if int(candidate_method_id) == int(method_id) and int(candidate_hash) == int(
+            path_hash
+        ):
+            return int(program_id)
+    route = getattr(packed, "rest_exact_route_to_program", None)
+    if not isinstance(route, Mapping):
+        return -1
+    maybe = route.get((method.upper(), path))
+    return maybe if isinstance(maybe, int) else -1
+
+
+def resolve_hot_exact_websocket_routes(
+    plan: KernelPlan,
+    packed: PackedKernel,
+    cache: ExactWebSocketCache,
+) -> Mapping[tuple[str, str], int]:
+    packed_id = id(packed)
+    cached = cache.get(packed_id)
+    if cached is not None:
+        return cached
+    exact: dict[tuple[str, str], int] = {}
+    for proto in ("ws", "wss"):
+        bucket = plan.proto_indices.get(proto)
+        if not isinstance(bucket, Mapping):
+            continue
+        exact_bucket = bucket.get("exact")
+        if not isinstance(exact_bucket, Mapping):
+            continue
+        for path, meta_index in exact_bucket.items():
+            if isinstance(path, str) and isinstance(meta_index, int):
+                exact[(proto, path)] = meta_index
+    cache[packed_id] = exact
+    return exact
+
+
+def resolve_program_id_from_exact_websocket(
+    plan: KernelPlan,
+    packed: PackedKernel,
+    protocol: str,
+    path: str,
+    cache: ExactWebSocketCache,
+) -> int:
+    exact = resolve_hot_exact_websocket_routes(plan, packed, cache)
+    maybe = exact.get((protocol, path))
+    return maybe if isinstance(maybe, int) else -1
+
+
+def resolve_hot_exact_jsonrpc_routes(
+    plan: KernelPlan,
+    cache: ExactJsonRpcCache,
+) -> Mapping[str, Mapping[str, tuple[int, str, str]]]:
+    plan_id = id(plan)
+    cached = cache.get(plan_id)
+    if cached is not None:
+        return cached
+
+    proto_indices = getattr(plan, "proto_indices", {}) or {}
+    exact_routes: dict[str, dict[str, tuple[int, str, str]]] = {}
+    if isinstance(proto_indices, Mapping):
+        for proto, bucket in proto_indices.items():
+            if not isinstance(proto, str) or not proto.endswith(".jsonrpc"):
+                continue
+            if not isinstance(bucket, Mapping):
+                continue
+            endpoints = bucket.get("endpoints")
+            if not isinstance(endpoints, Mapping):
+                continue
+            for endpoint, endpoint_bucket in endpoints.items():
+                if not isinstance(endpoint, str) or not endpoint:
+                    continue
+                if not isinstance(endpoint_bucket, Mapping):
+                    continue
+                method_map = exact_routes.setdefault(endpoint, {})
+                for rpc_method, entry in endpoint_bucket.items():
+                    if not isinstance(rpc_method, str) or not rpc_method:
+                        continue
+                    if not isinstance(entry, Mapping):
+                        continue
+                    meta_index = entry.get("meta_index")
+                    if not isinstance(meta_index, int):
+                        continue
+                    selector = str(entry.get("selector") or f"{endpoint}:{rpc_method}")
+                    method_map[rpc_method] = (meta_index, str(proto), selector)
+
+    frozen = {endpoint: dict(method_map) for endpoint, method_map in exact_routes.items()}
+    cache[plan_id] = frozen
+    return frozen
+
+
+def normalize_jsonrpc_mount_path(path: str) -> str:
+    normalized = str(path or "").rstrip("/")
+    return normalized or "/"

tigrbl_kernel/protocol_anchors.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any
+import warnings
+
+
+def canonical_protocol_anchor_order(
+    binding: str,
+    subevent: str,
+    *,
+    edge: str = "ok",
+) -> tuple[str, ...]:
+    del binding, subevent
+    order = [
+        "dispatch.exchange.select",
+        "dispatch.family.derive",
+        "dispatch.subevent.derive",
+        "framing.decode",
+        "framing.encode",
+        "transport.emit",
+        "transport.emit_complete",
+    ]
+    if edge == "err":
+        order.extend(("err.ctx.build", "err.classify", "err.transport.shape"))
+    return tuple(order)
+
+
+def python_protocol_anchor_trace(case: dict[str, Any]) -> tuple[str, ...]:
+    return canonical_protocol_anchor_order(
+        str(case.get("binding")),
+        str(case.get("subevent")),
+    )
+
+
+def rust_protocol_anchor_trace(case: dict[str, Any]) -> tuple[str, ...]:
+    del case
+    warnings.warn(
+        "rust_protocol_anchor_trace is deprecated; protocol anchors are Python-only.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    raise RuntimeError("rust_protocol_anchor_trace is unavailable.")
+
+
+__all__ = [
+    "canonical_protocol_anchor_order",
+    "python_protocol_anchor_trace",
+    "rust_protocol_anchor_trace",
+]

tigrbl_kernel/protocol_bindings.py

@@ -11,6 +11,7 @@ from tigrbl_core._spec.binding_spec import (
     webtransport_lane_for_profile,
     webtransport_runtime_family,
 )
+from tigrbl_kernel.resume_policy import compile_resume_policy
 
 
 def _unsupported(message: str) -> ValueError:
@@ -72,18 +73,30 @@ def compile_binding_protocol_plan(op_id: str, binding: Mapping[str, Any]) -> dic
             {"family": "request", "subevent": "response.emit"},
         )
     elif kind in {"http.stream", "https.stream"}:
-        validate_binding_profile_exchange(
+        exchange = validate_binding_profile_exchange(
             binding_kind=kind,
             exchange=str(binding.get("exchange") or "server_stream"),
         )
         validate_app_framing_for_binding(binding_kind=kind, framing=str(framing or "stream"))
         family = "stream"
         framing = str(framing or "stream")
-        anchors = ("handler.invoke", "transport.emit", "transport.emit_complete")
-        rows = (
-            {"family": "stream", "subevent": "stream.chunk"},
-            {"family": "stream", "subevent": "stream.close"},
-        )
+        if exchange == "client_stream":
+            anchors = (
+                "transport.receive",
+                "dispatch.subevent.derive",
+                "handler.invoke",
+                "transport.emit_complete",
+            )
+            rows = (
+                {"family": "stream", "subevent": "stream.chunk.received"},
+                {"family": "stream", "subevent": "stream.receive_complete"},
+            )
+        else:
+            anchors = ("handler.invoke", "transport.emit", "transport.emit_complete")
+            rows = (
+                {"family": "stream", "subevent": "stream.chunk"},
+                {"family": "stream", "subevent": "stream.close"},
+            )
     elif kind in {"http.sse", "https.sse"}:
         validate_binding_profile_exchange(
             binding_kind=kind,
@@ -239,8 +252,11 @@ def compile_binding_protocol_plan(op_id: str, binding: Mapping[str, Any]) -> dic
     if kind == "webtransport":
         event_key_inputs["lane"] = lane
         event_key_inputs["inner_framing"] = inner_framing
+    resume_policy = compile_resume_policy(kind, binding)
+    if resume_policy.enabled:
+        event_key_inputs["resume_mode"] = resume_policy.mode
 
-    return {
+    plan: dict[str, object] = {
         "op_id": op_id,
         "binding_kind": kind,
         "family": family,
@@ -252,6 +268,9 @@ def compile_binding_protocol_plan(op_id: str, binding: Mapping[str, Any]) -> dic
         },
         "lifecycle_rows": rows,
     }
+    if resume_policy.enabled:
+        plan["resume_policy"] = resume_policy.as_dict()
+    return plan
 
 
 def _required_mask(*, kind: str, family: str, framing: str) -> int:

tigrbl_kernel/protocol_chains/http_stream.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 from typing import Any
 
-ANCHORS: tuple[str, ...] = (
+SERVER_STREAM_ANCHORS: tuple[str, ...] = (
     "transport.ingress",
     "binding.match",
     "dispatch.exchange.select",
@@ -16,8 +16,41 @@ ANCHORS: tuple[str, ...] = (
     "transport.emit_complete",
 )
 
+CLIENT_STREAM_ANCHORS: tuple[str, ...] = (
+    "transport.ingress",
+    "binding.match",
+    "dispatch.exchange.select",
+    "dispatch.family.derive",
+    "dispatch.subevent.derive",
+    "request.body.receive",
+    "stream.chunk.received",
+    "stream.receive_complete",
+    "operation.resolve",
+    "handler.call",
+    "transport.emit_complete",
+)
+
 
 def compile_http_stream_chain(binding: Mapping[str, Any]) -> dict[str, object]:
+    exchange = str(binding.get("exchange") or "server_stream")
+    if exchange == "client_stream":
+        consumer = binding.get("consumer", "request_body")
+        if consumer not in {"request_body", "async_iterator"}:
+            raise ValueError("consumer must be request_body or async_iterator for HTTP client stream")
+        return {
+            "binding": "http.stream",
+            "exchange": "client_stream",
+            "family": "stream",
+            "path": binding.get("path"),
+            "method": binding.get("method", "POST"),
+            "consumer": consumer,
+            "anchors": CLIENT_STREAM_ANCHORS,
+            "break_conditions": ("request.body_complete", "disconnect"),
+            "err_target": "transport.close",
+            "completion_fence": "POST_HANDLER",
+        }
+    if exchange != "server_stream":
+        raise ValueError("HTTP stream exchange must be server_stream or client_stream")
     producer = binding.get("producer", "iterator")
     if producer not in {"iterator", "async_iterator"}:
         raise ValueError("producer must be iterator or async_iterator for HTTP stream")
@@ -28,7 +61,7 @@ def compile_http_stream_chain(binding: Mapping[str, Any]) -> dict[str, object]:
         "path": binding.get("path"),
         "method": binding.get("method", "GET"),
         "producer": producer,
-        "anchors": ANCHORS,
+        "anchors": SERVER_STREAM_ANCHORS,
         "break_conditions": ("producer.exhausted", "disconnect"),
         "err_target": "transport.close",
         "completion_fence": "POST_EMIT",