tigrbl-kernel 0.4.0.dev2__py3-none-any.whl → 0.4.1.dev6__py3-none-any.whl

tigrbl_kernel/__init__.py

@@ -25,6 +25,7 @@ from .measure import (
 )
 
 _LAZY_EXPORTS = {
+    "BatchOpPlan": "models",
     "Kernel": "core",
     "OpView": "models",
     "PackedKernel": "models",
@@ -83,6 +84,7 @@ __all__ = [
     "Kernel",
     "RustBackendConfig",
     "RustPlan",
+    "BatchOpPlan",
     "OpView",
     "PackedKernel",
     "SchemaIn",

tigrbl_kernel/_build.py

@@ -14,6 +14,7 @@ from tigrbl_atoms import StepFn
 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 . import events as _ev
@@ -24,7 +25,7 @@ from .atoms import (
     _is_persistent,
     _wrap_atom,
 )
-from .models import HotOpPlan, KernelPlan, OpKey, OpView, PackedKernel
+from .models import BatchOpPlan, HotOpPlan, KernelPlan, OpKey, OpView, PackedKernel
 from .measure import (
     load_packed_kernel_hot_sections,
     measure_packed_kernel,
@@ -121,6 +122,11 @@ def _phase_stamp(self: Any, model: type, alias: str) -> tuple[Any, ...]:
     specs = getattr(getattr(model, "ops", SimpleNamespace()), "by_alias", {})
     sp_list = specs.get(alias) or ()
     sp = sp_list[0] if sp_list else None
+    if sp is None:
+        sp = next(
+            (item for item in _opspecs(model) if getattr(item, "alias", None) == alias),
+            None,
+        )
     phase_lists = tuple(
         (
             phase,
@@ -185,6 +191,75 @@ def _prepend_phase_db_binding(
         chains[phase] = [_phase_db_step(), *steps]
 
 
+def _batch_policy_for_op(sp: Any | None, *, alias: str, target: str, persistent: bool) -> Mapping[str, Any]:
+    cfg = resolve_cfg(op=alias, opspec=sp).as_dict()
+    batch = cfg.get("batch")
+    if not isinstance(batch, Mapping):
+        return {"enabled": False}
+    policy = dict(batch)
+    allow_reads = bool(policy.get("allow_reads", False))
+    if target in {"read", "list"} and not allow_reads:
+        policy["enabled"] = False
+    if not persistent and not allow_reads:
+        policy["enabled"] = False
+    return policy
+
+
+def _is_batch_domain_run(run: Any) -> bool:
+    mod = getattr(run, "__module__", "") or ""
+    parts = mod.split(".")
+    try:
+        index = parts.index("atoms")
+    except ValueError:
+        return False
+    domain = parts[index + 1] if index + 1 < len(parts) else None
+    return domain in {"transport", "intent", "batch", "fanout"}
+
+
+def _batch_op_plan_from_policy(policy: Mapping[str, Any] | None) -> BatchOpPlan:
+    policy = policy if isinstance(policy, Mapping) else {}
+
+    def _int(name: str, default: int) -> int:
+        try:
+            return max(0, int(policy.get(name, default)))
+        except Exception:
+            return default
+
+    return BatchOpPlan(
+        enabled=bool(policy.get("enabled", False)),
+        max_size=_int("max_size", 64),
+        max_bytes=_int("max_bytes", 1_048_576),
+        max_delay_ms=_int("max_delay_ms", 1),
+        admission_timeout_ms=_int("admission_timeout_ms", 5),
+        conflict_policy=str(policy.get("conflict_policy", "single_fallback")),
+        overflow_policy=str(policy.get("overflow_policy", "backpressure")),
+        result_fanout=str(policy.get("result_fanout", "by_admission")),
+        allow_reads=bool(policy.get("allow_reads", False)),
+        max_queue_depth=_int("max_queue_depth", 1024),
+        max_in_flight=_int("max_in_flight", 16),
+    )
+
+
+def _batch_policy_for_meta(meta: Any) -> BatchOpPlan:
+    model = getattr(meta, "model", None)
+    alias = str(getattr(meta, "alias", "") or "")
+    target = str(getattr(meta, "target", alias) or alias).lower()
+    sp = next(
+        (item for item in _opspecs(model) if getattr(item, "alias", None) == alias),
+        None,
+    )
+    persist_policy = getattr(sp, "persist", "default")
+    persistent = persist_policy != "skip" and target not in {"read", "list"}
+    return _batch_op_plan_from_policy(
+        _batch_policy_for_op(
+            sp,
+            alias=alias,
+            target=target,
+            persistent=persistent,
+        )
+    )
+
+
 def _build_op(self, model: type, alias: str) -> Dict[str, List[StepFn]]:
     from .core import DEFAULT_PHASE_ORDER
 
@@ -201,11 +276,22 @@ def _build_op(self, model: type, alias: str) -> Dict[str, List[StepFn]]:
     specs = getattr(getattr(model, "ops", SimpleNamespace()), "by_alias", {})
     sp_list = specs.get(alias) or ()
     sp = sp_list[0] if sp_list else None
+    if sp is None:
+        sp = next(
+            (item for item in _opspecs(model) if getattr(item, "alias", None) == alias),
+            None,
+        )
     target = (getattr(sp, "target", alias) or "").lower()
     persist_policy = getattr(sp, "persist", "default")
     persistent = (
         persist_policy != "skip" and target not in {"read", "list"}
     ) or _is_persistent(chains)
+    batch_policy = _batch_policy_for_op(
+        sp,
+        alias=alias,
+        target=target,
+        persistent=persistent,
+    )
 
     try:
         _inject_atoms(
@@ -213,6 +299,7 @@ def _build_op(self, model: type, alias: str) -> Dict[str, List[StepFn]]:
             self._atoms() or (),
             persistent=persistent,
             target=target,
+            batch_policy=batch_policy,
         )
     except Exception:
         logger.exception(
@@ -240,6 +327,8 @@ def _build_ingress(self, app: Any) -> Dict[str, List[StepFn]]:
     order = {name: idx for idx, name in enumerate(_ev.all_events_ordered())}
     ingress_atoms: Dict[str, List[tuple[str, Any]]] = {}
     for anchor, run in self._atoms() or ():
+        if _is_batch_domain_run(run):
+            continue
         if not _ev.is_valid_event(anchor):
             continue
         phase = _ev.phase_for_event(anchor)
@@ -262,6 +351,8 @@ def _build_egress(self, app: Any) -> Dict[str, List[StepFn]]:
     order = {name: idx for idx, name in enumerate(_ev.all_events_ordered())}
     egress_atoms: Dict[str, List[tuple[str, Any]]] = {}
     for anchor, run in self._atoms() or ():
+        if _is_batch_domain_run(run):
+            continue
         if not _ev.is_valid_event(anchor):
             continue
         phase = _ev.phase_for_event(anchor)
@@ -939,8 +1030,18 @@ def _pack_kernel_plan(
     error_profile_segment_refs: list[int] = []
     program_error_profile_ids: list[int] = []
     program_hot_runner_ids: list[int] = []
+    batch_policy_index: dict[BatchOpPlan, int] = {}
+    batch_policy_table: list[BatchOpPlan] = []
+    program_batch_policy_ids: list[int] = []
     for program_id, _meta in enumerate(plan.opmeta):
         meta = plan.opmeta[program_id]
+        batch_plan = _batch_policy_for_meta(meta)
+        batch_policy_id = batch_policy_index.get(batch_plan)
+        if batch_policy_id is None:
+            batch_policy_id = len(batch_policy_table)
+            batch_policy_index[batch_plan] = batch_policy_id
+            batch_policy_table.append(batch_plan)
+        program_batch_policy_ids.append(batch_policy_id)
         seg_offset = op_segment_offsets[program_id]
         seg_length = op_segment_lengths[program_id]
         by_phase: dict[str, list[int]] = {}
@@ -1106,6 +1207,8 @@ def _pack_kernel_plan(
                 program_hot_runner_id=hot_runner_id,
                 param_shape_id=param_shape_id,
                 transport_kind_id=transport_kind_id,
+                batch_policy_id=batch_policy_id,
+                batch=batch_plan,
                 compiled_param_phase_steps=compiled_param_phase_steps,
                 websocket_path=websocket_fast_path[0] if websocket_fast_path is not None else "",
                 websocket_protocol=websocket_fast_path[1] if websocket_fast_path is not None else "",
@@ -1142,6 +1245,8 @@ def _pack_kernel_plan(
         param_shape_header_hashes=tuple(param_shape_header_hashes),
         program_param_shape_ids=tuple(program_param_shape_ids),
         program_transport_kind_ids=tuple(program_transport_kind_ids),
+        batch_policy_table=tuple(batch_policy_table),
+        program_batch_policy_ids=tuple(program_batch_policy_ids),
         segment_offsets=tuple(segment_offsets),
         segment_lengths=tuple(segment_lengths),
         segment_step_ids=tuple(segment_step_ids),

tigrbl_kernel/atoms.py

@@ -4,6 +4,7 @@ import importlib
 import inspect
 import logging
 import pkgutil
+from functools import lru_cache
 from types import SimpleNamespace
 from typing import (
     Any,
@@ -16,6 +17,7 @@ from typing import (
     Sequence,
     cast,
 )
+from collections.abc import Mapping as AbcMapping
 
 from tigrbl_typing.phases import HOOK_PHASES as HOOK_PHASES
 
@@ -45,6 +47,7 @@ _COMPILED_PHASE_DB_REQUIRED_ATOM_NAMES = frozenset(
         "sys.commit_tx",
     }
 )
+_BATCH_DOMAINS = frozenset({"transport", "intent", "batch", "fanout"})
 
 
 def _is_async_callable(run: _AtomRun) -> bool:
@@ -128,6 +131,18 @@ def _policy_atom_name(
 
 
 def _use_two_args_for(run: _AtomRun) -> bool:
+    try:
+        return _use_two_args_for_cached(run)
+    except TypeError:
+        return _use_two_args_for_uncached(run)
+
+
+@lru_cache(maxsize=2048)
+def _use_two_args_for_cached(run: _AtomRun) -> bool:
+    return _use_two_args_for_uncached(run)
+
+
+def _use_two_args_for_uncached(run: _AtomRun) -> bool:
     try:
         params = tuple(inspect.signature(run).parameters.values())
         positional = [
@@ -291,6 +306,7 @@ def _inject_atoms(
     *,
     persistent: bool,
     target: str | None = None,
+    batch_policy: Mapping[str, Any] | None = None,
 ) -> None:
     order = {name: i for i, name in enumerate(_ev.all_events_ordered())}
 
@@ -324,7 +340,13 @@ def _inject_atoms(
             continue
 
         domain, _subject = _infer_domain_subject(run)
-        if not persistent and persist_tied:
+        batch_enabled = bool(
+            isinstance(batch_policy, AbcMapping)
+            and bool(batch_policy.get("enabled", False))
+        )
+        if domain in _BATCH_DOMAINS and not batch_enabled:
+            continue
+        if not persistent and persist_tied and not (domain in _BATCH_DOMAINS and batch_enabled):
             if not (
                 domain == "sys"
                 and isinstance(_subject, str)

tigrbl_kernel/helpers.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
+from dataclasses import fields
 import inspect
 import logging
 from typing import Any, Iterable, Mapping, Optional, Sequence
 
-from tigrbl_atoms.types import AtomFailure, FailedCtx, build_error_ctx
+from tigrbl_atoms.types import AtomFailure, BaseCtx, FailedCtx, build_error_ctx
 from tigrbl_typing.phases import normalize_phase
 
 try:
@@ -15,6 +16,26 @@ except Exception:  # pragma: no cover
 logger = logging.getLogger(__name__)
 
 
+def _merge_promoted_ctx(ctx: Any, promoted: BaseCtx[Any, Any]) -> None:
+    for field_info in fields(type(promoted)):
+        name = field_info.name
+        value = getattr(promoted, name)
+        if name == "bag":
+            if isinstance(value, Mapping):
+                for bag_key, bag_value in value.items():
+                    if bag_key == "result" and hasattr(promoted, "result"):
+                        continue
+                    ctx[bag_key] = bag_value
+            continue
+        if name == "temp":
+            ctx.temp = dict(value or {})
+            continue
+        if name in {"env", "error", "phase", "current_phase", "error_phase"}:
+            setattr(ctx, name, value)
+            continue
+        ctx[name] = value
+
+
 def _normalize_payload(payload: Any) -> Any:
     if isinstance(payload, (str, int, float, bool)) or payload is None:
         return payload
@@ -109,7 +130,9 @@ async def _run_chain(ctx: Any, chain: Optional[Iterable[Any]], *, phase: str) ->
                 if isinstance(err, BaseException):
                     raise err
                 raise AtomFailure(err)
-            if rv is not None and rv is not ctx:
+            if isinstance(rv, BaseCtx):
+                _merge_promoted_ctx(ctx, rv)
+            elif rv is not None and rv is not ctx:
                 ctx.result = rv
             if trace_active:
                 _trace.end(ctx, seq, status=_trace.OK)

tigrbl_kernel/loop_modes.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+
+_RECEIVE_CAPABILITIES = {"recv", "receive"}
+
+
+def select_loop_mode(
+    *,
+    binding: str,
+    subevent_handlers: Iterable[str] = (),
+    explicit_mode: str | None = None,
+    capabilities: Iterable[str] = (),
+) -> str:
+    handlers = tuple(subevent_handlers or ())
+    caps = {str(capability) for capability in capabilities or ()}
+    if explicit_mode not in {None, "owner", "dispatch"}:
+        raise ValueError(f"unsupported loop mode {explicit_mode!r}")
+
+    if explicit_mode == "owner" and handlers:
+        raise ValueError("owner loop mode cannot be selected with dispatch handlers")
+    if explicit_mode == "dispatch":
+        if not handlers:
+            raise ValueError("dispatch loop mode requires subevent handlers")
+        if caps and caps.isdisjoint(_RECEIVE_CAPABILITIES):
+            raise ValueError("dispatch loop mode requires receive capability")
+        return "dispatch"
+    if explicit_mode == "owner":
+        return "owner"
+    return "dispatch" if handlers else "owner"
+
+
+__all__ = ["select_loop_mode"]

tigrbl_kernel/models.py

@@ -74,6 +74,21 @@ class OpMeta:
     target: str
 
 
+@dataclass(frozen=True, slots=True)
+class BatchOpPlan:
+    enabled: bool = False
+    max_size: int = 64
+    max_bytes: int = 1_048_576
+    max_delay_ms: int = 1
+    admission_timeout_ms: int = 5
+    conflict_policy: str = "single_fallback"
+    overflow_policy: str = "backpressure"
+    result_fanout: str = "by_admission"
+    allow_reads: bool = False
+    max_queue_depth: int = 1024
+    max_in_flight: int = 16
+
+
 @dataclass(frozen=True, slots=True)
 class CompiledPhase:
     name: str
@@ -112,6 +127,8 @@ class HotOpPlan:
     program_hot_runner_id: int = 0
     param_shape_id: int = -1
     transport_kind_id: int = 0
+    batch_policy_id: int = -1
+    batch: BatchOpPlan = field(default_factory=BatchOpPlan)
     compiled_param_phase_steps: tuple[tuple[str, tuple[Any, ...]], ...] = ()
     websocket_path: str = ""
     websocket_protocol: str = ""
@@ -283,6 +300,8 @@ class PackedKernel:
     param_shape_header_hashes: tuple[int, ...] = ()
     program_param_shape_ids: tuple[int, ...] = ()
     program_transport_kind_ids: tuple[int, ...] = ()
+    batch_policy_table: tuple[BatchOpPlan, ...] = ()
+    program_batch_policy_ids: tuple[int, ...] = ()
 
     segment_offsets: tuple[int, ...] = ()
     segment_lengths: tuple[int, ...] = ()

tigrbl_kernel/ordering.py

@@ -18,21 +18,51 @@ from .labels import Label
 _PREF: Dict[str, Tuple[str, ...]] = {
     _ev.INGRESS_CTX_INIT: ("ingress:ctx_init",),
     _ev.INGRESS_TRANSPORT_EXTRACT: ("ingress:transport_extract",),
+    _ev.BATCH_TRANSPORT_UNIT_CAPTURE: ("transport:unit_capture",),
+    _ev.BATCH_TRANSPORT_SINK_BIND: ("transport:sink_bind",),
     _ev.INGRESS_INPUT_PREPARE: ("ingress:input_prepare",),
     _ev.DISPATCH_BINDING_MATCH: ("dispatch:binding_match",),
     _ev.DISPATCH_BINDING_PARSE: ("dispatch:binding_parse",),
     _ev.DISPATCH_INPUT_NORMALIZE: ("dispatch:input_normalize",),
     _ev.DISPATCH_OP_RESOLVE: ("dispatch:op_resolve",),
+    _ev.BATCH_INTENT_BUILD: ("intent:build",),
+    _ev.BATCH_PREKEY: ("intent:prekey",),
     _ev.DEP_SECURITY: (_ev.DEP_SECURITY,),
     _ev.DEP_EXTRA: (_ev.DEP_EXTRA,),
+    _ev.BATCH_GROUP_KEY: ("intent:final_group_key",),
+    _ev.BATCH_ADMIT: ("batch:admit",),
+    _ev.BATCH_DEDUPE: ("batch:dedupe",),
+    _ev.BATCH_SEAL_CHECK: ("batch:seal_check",),
+    _ev.BATCH_AWAIT_SEAL: ("batch:await_seal",),
     _ev.SCHEMA_COLLECT_IN: ("schema:collect_in",),
+    _ev.BATCH_PREPARE_EXECUTE: ("batch:prepare_execute",),
     _ev.IN_VALIDATE: ("wire:build_in", "wire:validate_in"),
-    _ev.SYS_TX_BEGIN: ("sys:txn:begin",),
+    _ev.SYS_TX_BEGIN: ("sys:start_tx",),
+    _ev.BATCH_TX_BEGIN: ("batch:tx_begin",),
     _ev.RESOLVE_VALUES: ("resolve:assemble", "resolve:paired_gen"),
     _ev.PRE_FLUSH: ("storage:to_stored",),
     _ev.EMIT_ALIASES_PRE: ("emit:paired_pre",),
-    _ev.SYS_HANDLER_PERSISTENCE: ("sys:handler:crud",),
-    _ev.SYS_TX_COMMIT: ("sys:txn:commit",),
+    _ev.BATCH_EXECUTE: ("batch:execute",),
+    _ev.SYS_HANDLER_PERSISTENCE: (
+        "sys:handler_create",
+        "sys:handler_read",
+        "sys:handler_update",
+        "sys:handler_replace",
+        "sys:handler_merge",
+        "sys:handler_delete",
+        "sys:handler_list",
+        "sys:handler_clear",
+        "sys:handler_bulk_create",
+        "sys:handler_bulk_update",
+        "sys:handler_bulk_replace",
+        "sys:handler_bulk_merge",
+        "sys:handler_bulk_delete",
+        "sys:handler_persistence",
+    ),
+    _ev.BATCH_RESULT_SLOTS: ("batch:result_slots",),
+    _ev.BATCH_PRECOMMIT_VALIDATE: ("batch:precommit_validate",),
+    _ev.SYS_TX_COMMIT: ("sys:commit_tx",),
+    _ev.BATCH_COMMIT: ("batch:commit",),
     _ev.POST_FLUSH: ("refresh:demand",),
     _ev.EMIT_ALIASES_POST: ("emit:paired_post",),
     _ev.SCHEMA_COLLECT_OUT: ("schema:collect_out",),
@@ -43,7 +73,10 @@ _PREF: Dict[str, Tuple[str, ...]] = {
     _ev.EGRESS_HEADERS_APPLY: ("egress:headers_apply",),
     _ev.EGRESS_HTTP_FINALIZE: ("egress:http_finalize",),
     _ev.EGRESS_TO_TRANSPORT_RESPONSE: ("egress:to_transport_response",),
+    _ev.BATCH_EGRESS_SHAPE: ("fanout:shape",),
     _ev.EGRESS_ASGI_SEND: ("egress:asgi_send",),
+    _ev.BATCH_FANOUT_EMIT: ("fanout:emit_many",),
+    _ev.BATCH_CLEANUP: ("batch:cleanup",),
     _ev.EMIT_ALIASES_READ: ("emit:readtime_alias",),
     _ev.OUT_DUMP: (
         "wire:dump",

tigrbl_kernel/protocol_completion.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def compile_completion_fence(binding: dict[str, Any]) -> dict[str, Any]:
+    transport = binding.get("transport")
+    needs_fence = transport in {"stream", "websocket", "webtransport", "datagram"} or binding.get("phase") == "EMIT"
+    if not needs_fence and binding.get("send_completion") == "synchronous":
+        return {
+            "completion_fence": None,
+            "runtime_owned": True,
+            "public_hook_phase": False,
+            "after_phase": binding.get("phase", "EMIT"),
+            "explicit_ack_required": False,
+        }
+    return {
+        "completion_fence": "POST_EMIT",
+        "runtime_owned": True,
+        "public_hook_phase": False,
+        "after_phase": binding.get("phase", "EMIT"),
+        "explicit_ack_required": True,
+    }
+
+
+def validate_completion_hook_phase(phase: str) -> None:
+    if phase == "POST_EMIT":
+        raise ValueError("POST_EMIT is a runtime-owned completion fence hook phase")
+
+
+__all__ = ["compile_completion_fence", "validate_completion_hook_phase"]

tigrbl_kernel/protocol_fusion.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+
+def _tuple_values(segment: Mapping[str, Any], key: str) -> tuple[Any, ...]:
+    value = segment.get(key, ())
+    if value is None:
+        return ()
+    return tuple(value)
+
+
+def _barrier(segment: Mapping[str, Any]) -> bool:
+    return bool(segment.get("barrier")) or str(segment.get("barrier_kind", "")) in {
+        "transaction",
+        "transport",
+        "error",
+        "completion",
+    }
+
+
+def fuse_protocol_segments(
+    segments: Iterable[Mapping[str, Any]],
+    *,
+    force: bool = False,
+) -> list[dict[str, object]]:
+    items = [dict(segment) for segment in segments]
+    if force and sum(1 for segment in items if _barrier(segment)) > 1:
+        raise ValueError("protocol segment fusion cannot cross transaction, transport, or error barriers")
+
+    fused: list[dict[str, object]] = []
+    bucket: list[dict[str, Any]] = []
+
+    def flush() -> None:
+        nonlocal bucket
+        if not bucket:
+            return
+        if len(bucket) == 1:
+            item = dict(bucket[0])
+            if "err_target" in item:
+                item["err_targets"] = (item["err_target"],)
+            fused.append(item)
+        else:
+            merged: dict[str, object] = {
+                "segment_id": "+".join(str(item["segment_id"]) for item in bucket),
+                "source_segments": tuple(str(item["segment_id"]) for item in bucket),
+                "anchors": tuple(anchor for item in bucket for anchor in _tuple_values(item, "anchors")),
+            }
+            atoms = tuple(atom for item in bucket for atom in _tuple_values(item, "atoms"))
+            if atoms:
+                merged["atoms"] = atoms
+            err_targets = tuple(item["err_target"] for item in bucket if "err_target" in item)
+            if err_targets:
+                merged["err_targets"] = err_targets
+            fused.append(merged)
+        bucket = []
+
+    for segment in items:
+        if _barrier(segment):
+            flush()
+            fused.append(segment)
+        else:
+            bucket.append(segment)
+    flush()
+    return fused
+
+
+def linearize_segment_anchors(segments: Iterable[Mapping[str, Any]]) -> tuple[Any, ...]:
+    return tuple(anchor for segment in segments for anchor in _tuple_values(segment, "anchors"))
+
+
+__all__ = ["fuse_protocol_segments", "linearize_segment_anchors"]

tigrbl_kernel/protocol_legality_matrix.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+
+REQUIRED_COLUMNS = {
+    "binding",
+    "subevent",
+    "phase",
+    "segment",
+    "atom",
+    "legality",
+    "transaction_unit",
+    "hookable",
+    "emits_bytes",
+    "requires_channel",
+    "ok_target",
+    "err_target",
+    "err_ctx",
+    "err_kind",
+    "rollback_required",
+    "terminal_policy",
+}
+
+
+def _row(binding: str, subevent: str, atom: str, **overrides: Any) -> dict[str, Any]:
+    row = {
+        "binding": binding,
+        "subevent": subevent,
+        "phase": "EMIT" if "emit" in atom else "HANDLER",
+        "segment": "transport" if atom.startswith("transport.") else "handler",
+        "atom": atom,
+        "legality": "required",
+        "transaction_unit": "request",
+        "hookable": False,
+        "emits_bytes": atom == "transport.emit",
+        "requires_channel": binding not in {"http.rest", "http.jsonrpc"},
+        "ok_target": "NEXT",
+        "err_target": "ON_PROTOCOL_ERROR",
+        "err_ctx": "ErrorCtx",
+        "err_kind": "protocol_error",
+        "rollback_required": False,
+        "terminal_policy": "continue",
+    }
+    row.update(overrides)
+    return row
+
+
+def generate_legality_matrix() -> list[dict[str, Any]]:
+    rows = [
+        _row("http.rest", "request.received", "CALL_HANDLER", requires_channel=False),
+        _row("http.jsonrpc", "rpc.request", "CALL_HANDLER", requires_channel=False),
+        _row("http.stream", "stream.chunk.emit", "transport.emit"),
+        _row("http.sse", "message.emit", "transport.emit"),
+        _row("http.sse", "message.emit_complete", "transport.emit_complete"),
+        _row("websocket", "session.open", "transport.accept", phase="PRE_HANDLER"),
+        _row("websocket", "session.open", "framing.decode", phase="PRE_HANDLER"),
+        _row("webtransport.stream", "stream.chunk.received", "framing.decode"),
+        _row("webtransport.datagram", "datagram.received", "framing.decode"),
+        _row("webtransport.app_frame", "message.received", "framing.decode"),
+    ]
+    return rows
+
+
+def validate_legality_matrix(rows: Iterable[Mapping[str, Any]]) -> dict[str, bool]:
+    for row in rows:
+        missing = REQUIRED_COLUMNS - set(row)
+        if missing:
+            raise ValueError(f"legality matrix row missing required columns: {sorted(missing)}")
+        if row.get("legality") == "forbidden" and row.get("atom") == "transport.emit":
+            raise ValueError("legality matrix forbids illegal transport atom")
+    return {"passed": True}
+
+
+def validate_protocol_plan(*, binding: str, subevent: str, phase: str, atoms: tuple[str, ...]) -> None:
+    rows = [
+        row
+        for row in generate_legality_matrix()
+        if row["binding"] == binding and row["subevent"] == subevent and row["phase"] == phase
+    ]
+    allowed = {row["atom"] for row in rows}
+    if "transport.emit" in atoms and "transport.emit" not in allowed:
+        raise ValueError("forbidden atom violates legality matrix")
+    required = {row["atom"] for row in rows if row["legality"] == "required"}
+    missing = required - set(atoms)
+    if missing:
+        raise ValueError(f"required atom missing from legality plan: {sorted(missing)}")
+
+
+def _key(row: Mapping[str, Any]) -> tuple[Any, Any, Any, Any]:
+    return (row.get("binding"), row.get("subevent"), row.get("phase"), row.get("atom"))
+
+
+def diff_legality_matrix(
+    old: Iterable[Mapping[str, Any]],
+    new: Iterable[Mapping[str, Any]],
+) -> dict[str, list[dict[str, Any]]]:
+    old_map = {_key(row): dict(row) for row in old}
+    new_map = {_key(row): dict(row) for row in new}
+    return {
+        "added": [new_map[key] for key in new_map.keys() - old_map.keys()],
+        "removed": [old_map[key] for key in old_map.keys() - new_map.keys()],
+        "changed": [
+            {"old": old_map[key], "new": new_map[key]}
+            for key in old_map.keys() & new_map.keys()
+            if old_map[key] != new_map[key]
+        ],
+    }
+
+
+__all__ = [
+    "diff_legality_matrix",
+    "generate_legality_matrix",
+    "validate_legality_matrix",
+    "validate_protocol_plan",
+]