tigrbl-kernel 0.1.0.dev1__py3-none-any.whl

tigrbl_kernel/kernel/__init__.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, Optional
+
+from tigrbl_runtime.hook_types import StepFn
+from tigrbl_runtime.executor import _Ctx, _invoke
+from .core import Kernel
+from .models import OpView, SchemaIn, SchemaOut
+
+_default_kernel = Kernel()
+
+
+def get_cached_specs(model: type) -> Mapping[str, Any]:
+    """Atoms can call this; zero per-request collection."""
+    return _default_kernel.get_specs(model)
+
+
+def build_phase_chains(model: type, alias: str) -> Dict[str, List[StepFn]]:
+    return _default_kernel.build_op(model, alias)
+
+
+def plan_labels(model: type, alias: str) -> list[str]:
+    return _default_kernel.plan_labels(model, alias)
+
+
+async def run(
+    model: type,
+    alias: str,
+    *,
+    db: Any,
+    request: Any | None = None,
+    ctx: Optional[Mapping[str, Any]] = None,
+) -> Any:
+    phases = _default_kernel.build_op(model, alias)
+    base_ctx = _Ctx.ensure(request=request, db=db, seed=ctx)
+    return await _invoke(request=request, db=db, phases=phases, ctx=base_ctx)
+
+
+__all__ = [
+    "Kernel",
+    "OpView",
+    "SchemaIn",
+    "SchemaOut",
+    "get_cached_specs",
+    "_default_kernel",
+    "build_phase_chains",
+    "plan_labels",
+    "run",
+]

tigrbl_kernel/kernel/atoms.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+import importlib
+import inspect
+import logging
+import pkgutil
+from types import SimpleNamespace
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    List,
+    Mapping,
+    Optional,
+    Sequence,
+    cast,
+)
+
+from tigrbl_runtime.hook_types import PHASES as HOOK_PHASES
+from tigrbl_runtime.hook_types import StepFn
+from tigrbl_runtime import events as _ev, ordering as _ordering, system as _sys
+
+logger = logging.getLogger(__name__)
+
+_AtomRun = Callable[[Optional[object], Any], Any]
+_DiscoveredAtom = tuple[str, _AtomRun]
+
+
+def _discover_atoms() -> list[_DiscoveredAtom]:
+    out: list[_DiscoveredAtom] = []
+    try:
+        import tigrbl_concrete.atoms as atoms_pkg  # type: ignore
+    except Exception:
+        return out
+
+    for info in pkgutil.walk_packages(atoms_pkg.__path__, atoms_pkg.__name__ + "."):  # type: ignore[attr-defined]
+        if info.ispkg:
+            continue
+        try:
+            mod = importlib.import_module(info.name)
+            anchor = getattr(mod, "ANCHOR", None)
+            run = getattr(mod, "run", None)
+            if isinstance(anchor, str) and callable(run):
+                out.append((anchor, run))
+        except Exception:
+            continue
+    logger.debug("kernel: discovered %d atoms", len(out))
+    return out
+
+
+def _infer_domain_subject(run: _AtomRun) -> tuple[Optional[str], Optional[str]]:
+    mod = getattr(run, "__module__", "") or ""
+    parts = mod.split(".")
+    try:
+        i = parts.index("atoms")
+        return (
+            parts[i + 1] if i + 1 < len(parts) else None,
+            parts[i + 2] if i + 2 < len(parts) else None,
+        )
+    except ValueError:
+        return None, None
+
+
+def _make_label(anchor: str, run: _AtomRun) -> Optional[str]:
+    domain, subject = _infer_domain_subject(run)
+    return f"atom:{domain}:{subject}@{anchor}" if (domain and subject) else None
+
+
+def _wrap_atom(run: _AtomRun, *, anchor: str) -> StepFn:
+    use_two_args = True
+    try:
+        params = tuple(inspect.signature(run).parameters.values())
+        positional = [
+            p
+            for p in params
+            if p.kind
+            in (
+                inspect.Parameter.POSITIONAL_ONLY,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            )
+        ]
+        # Kernel atoms default to ``run(obj, ctx)``. Support legacy
+        # ``run(ctx)`` atoms without masking TypeError raised inside the atom.
+        use_two_args = len(positional) != 1
+    except (TypeError, ValueError):
+        use_two_args = True
+
+    async def _step(ctx: Any) -> Any:
+        if use_two_args:
+            rv = run(None, ctx)
+        else:
+            rv = run(ctx)  # type: ignore[misc]
+        if hasattr(rv, "__await__"):
+            return await cast(Any, rv)
+        return rv
+
+    label = getattr(run, "__tigrbl_label", None)
+    if not isinstance(label, str):
+        label = _make_label(anchor, run)
+    if label:
+        setattr(_step, "__tigrbl_label", label)
+    return _step
+
+
+def _hook_phase_chains(model: type, alias: str) -> Dict[str, List[StepFn]]:
+    hooks_root = getattr(model, "hooks", None) or SimpleNamespace()
+    alias_ns = getattr(hooks_root, alias, None)
+    out: Dict[str, List[StepFn]] = {ph: [] for ph in HOOK_PHASES}
+    if alias_ns is None:
+        return out
+    for phase in HOOK_PHASES:
+        out[phase] = list(getattr(alias_ns, phase, []) or [])
+    return out
+
+
+def _is_persistent(chains: Mapping[str, Sequence[StepFn]]) -> bool:
+    for fn in chains.get("START_TX", ()) or ():
+        if getattr(fn, "__name__", "") == "start_tx":
+            return True
+    for fn in chains.get("PRE_TX_BEGIN", ()) or ():
+        if getattr(fn, "__name__", "") == "mark_skip_persist":
+            return False
+    return False
+
+
+def _label_dep_atom(*, kind: str, index: int, anchor: str) -> str:
+    return f"hook:dep:{kind}:{index}@{anchor}"
+
+
+def _make_dep_atom_step(run_fn: _AtomRun, dep: Any, *, label: str) -> StepFn:
+    async def _step(ctx: Any) -> Any:
+        rv = run_fn(dep, ctx)
+        if hasattr(rv, "__await__"):
+            return await cast(Any, rv)
+        return rv
+
+    setattr(_step, "__tigrbl_label", label)
+    return _step
+
+
+def _inject_pre_tx_dep_atoms(chains: Dict[str, List[StepFn]], sp: Any | None) -> None:
+    if sp is None:
+        return
+    try:
+        from tigrbl_concrete.atoms.dep.security import run as sec_run
+        from tigrbl_concrete.atoms.dep.extra import run as dep_run
+    except Exception:
+        return
+
+    pre_tx = chains.setdefault("PRE_TX_BEGIN", [])
+    for idx, dep in enumerate(getattr(sp, "secdeps", ()) or ()):
+        pre_tx.append(
+            _make_dep_atom_step(
+                sec_run,
+                dep,
+                label=_label_dep_atom(
+                    kind="security",
+                    index=idx,
+                    anchor=_ev.DEP_SECURITY,
+                ),
+            )
+        )
+    for idx, dep in enumerate(getattr(sp, "deps", ()) or ()):
+        pre_tx.append(
+            _make_dep_atom_step(
+                dep_run,
+                dep,
+                label=_label_dep_atom(
+                    kind="extra",
+                    index=idx,
+                    anchor=_ev.DEP_EXTRA,
+                ),
+            )
+        )
+
+
+def _inject_atoms(
+    chains: Dict[str, List[StepFn]],
+    atoms: Iterable[_DiscoveredAtom],
+    *,
+    persistent: bool,
+) -> None:
+    order = {name: i for i, name in enumerate(_ev.all_events_ordered())}
+
+    def _sort_key(item: _DiscoveredAtom) -> tuple[int, int]:
+        anchor, run = item
+        anchor_idx = order.get(anchor, 10_000)
+        domain, subject = _infer_domain_subject(run)
+        token = f"{domain}:{subject}" if domain and subject else ""
+        pref = _ordering._PREF.get(anchor, ())
+        token_idx = pref.index(token) if token in pref else 10_000
+        return anchor_idx, token_idx
+
+    for anchor, run in sorted(atoms, key=_sort_key):
+        if _ev.is_valid_event(anchor):
+            info = _ev.get_anchor_info(anchor)
+            phase = info.phase
+            persist_tied = info.persist_tied
+        elif anchor in _ev.PHASES:
+            phase = anchor
+            persist_tied = False
+        else:
+            continue
+
+        if phase in ("START_TX", "END_TX"):
+            continue
+        if not persistent and persist_tied:
+            continue
+        if anchor == _ev.SYS_HANDLER_PERSISTENCE and chains.get("HANDLER"):
+            continue
+        domain, _subject = _infer_domain_subject(run)
+        if domain == "dep":
+            continue
+
+        chains.setdefault(phase, []).append(_wrap_atom(run, anchor=anchor))
+
+
+def _inject_txn_system_steps(
+    chains: Dict[str, List[StepFn]], *, model: Any | None = None
+) -> None:
+    start_anchor, start_run = _sys.get("txn", "begin")
+    end_anchor, end_run = _sys.get("txn", "commit")
+    chains.setdefault(start_anchor, []).append(
+        _wrap_atom(start_run, anchor=start_anchor)
+    )
+
+    if not chains.get(_sys.HANDLER) and _sys.can_resolve_handler(model):
+        handler_anchor, handler_run = _sys.get("handler", "crud")
+        chains.setdefault(handler_anchor, []).append(
+            _wrap_atom(handler_run, anchor=handler_anchor)
+        )
+
+    chains.setdefault(end_anchor, []).append(_wrap_atom(end_run, anchor=end_anchor))

tigrbl_kernel/kernel/cache.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import threading
+import weakref
+from typing import Any, Dict, Generic, Mapping, Optional, Sequence, TypeVar
+
+from tigrbl_canon.mapping.column_mro_collect import mro_collect_columns
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class _WeakMaybeDict(Generic[K, V]):
+    """Dictionary that uses weak references when possible.
+
+    Falls back to strong references when ``key`` cannot be weakly referenced.
+    """
+
+    def __init__(self) -> None:
+        self._weak: "weakref.WeakKeyDictionary[Any, V]" = weakref.WeakKeyDictionary()
+        self._strong: Dict[int, tuple[Any, V]] = {}
+
+    def _use_weak(self, key: Any) -> bool:
+        try:
+            weakref.ref(key)
+            return True
+        except TypeError:
+            return False
+
+    def __setitem__(self, key: K, value: V) -> None:
+        if self._use_weak(key):
+            self._weak[key] = value
+        else:
+            self._strong[id(key)] = (key, value)
+
+    def __getitem__(self, key: K) -> V:
+        if self._use_weak(key):
+            return self._weak[key]
+        return self._strong[id(key)][1]
+
+    def get(self, key: K, default: Optional[V] = None) -> Optional[V]:
+        if self._use_weak(key):
+            return self._weak.get(key, default)
+        return self._strong.get(id(key), (None, default))[1]
+
+    def setdefault(self, key: K, default: V) -> V:
+        if self._use_weak(key):
+            return self._weak.setdefault(key, default)
+        return self._strong.setdefault(id(key), (key, default))[1]
+
+    def pop(self, key: K, default: Optional[V] = None) -> Optional[V]:
+        if self._use_weak(key):
+            return self._weak.pop(key, default)
+        return self._strong.pop(id(key), (None, default))[1]
+
+
+class _SpecsOnceCache:
+    """Thread-safe, compute-once cache of per-model column specs."""
+
+    def __init__(self) -> None:
+        self._d: Dict[type, Mapping[str, Any]] = {}
+        self._lock = threading.Lock()
+
+    def get(self, model: type) -> Mapping[str, Any]:
+        try:
+            return self._d[model]
+        except KeyError:
+            pass
+        with self._lock:
+            rv = self._d.get(model)
+            if rv is None:
+                rv = mro_collect_columns(model)
+                self._d[model] = rv
+        return rv
+
+    def prime(self, models: Sequence[type]) -> None:
+        for model in models:
+            self.get(model)
+
+    def invalidate(self, model: Optional[type] = None) -> None:
+        with self._lock:
+            if model is None:
+                self._d.clear()
+            else:
+                self._d.pop(model, None)

tigrbl_kernel/kernel/core.py

@@ -0,0 +1,582 @@
+from __future__ import annotations
+
+import logging
+import re
+import threading
+from types import SimpleNamespace
+from typing import Any, ClassVar, Dict, List, Mapping, Optional, Sequence, Tuple
+
+from tigrbl_runtime.hook_types import StepFn
+from tigrbl_runtime.executor import _Ctx, _invoke
+from tigrbl_runtime import events as _ev
+from .atoms import (
+    _DiscoveredAtom,
+    _discover_atoms,
+    _hook_phase_chains,
+    _inject_atoms,
+    _inject_pre_tx_dep_atoms,
+    _inject_txn_system_steps,
+    _is_persistent,
+    _wrap_atom,
+)
+from .cache import _SpecsOnceCache, _WeakMaybeDict
+from .models import KernelPlan, OpKey, OpMeta, OpView
+from tigrbl_runtime.labels import label_hook
+from .opview_compiler import compile_opview_from_specs
+
+logger = logging.getLogger(__name__)
+
+
+class _RestMatcher:
+    """REST selector matcher supporting exact and templated paths."""
+
+    def __init__(self) -> None:
+        self._exact: dict[tuple[str, str], int] = {}
+        self._templated: list[tuple[str, re.Pattern[str], tuple[str, ...], int]] = []
+        self._selectors: dict[str, int] = {}
+
+    @staticmethod
+    def _normalize_path(path: str) -> str:
+        p = path if path.startswith("/") else f"/{path}"
+        return p.rstrip("/") or "/"
+
+    def add(self, method: str, path: str, meta_index: int) -> None:
+        m = method.upper()
+        normalized = self._normalize_path(path)
+        self._selectors[f"{m} {normalized}"] = meta_index
+        if "{" not in normalized:
+            self._exact[(m, normalized)] = meta_index
+            return
+
+        names = tuple(re.findall(r"\{([^{}]+)\}", normalized))
+        pattern = "^" + re.sub(r"\{([^{}]+)\}", r"(?P<\1>[^/]+)", normalized) + "$"
+        self._templated.append((m, re.compile(pattern), names, meta_index))
+
+    def match(self, method: str, path: str) -> tuple[int, dict[str, str]]:
+        m = method.upper()
+        normalized = self._normalize_path(path)
+
+        exact = self._exact.get((m, normalized))
+        if exact is not None:
+            return exact, {}
+
+        for templ_method, pattern, names, meta_index in self._templated:
+            if templ_method != m:
+                continue
+            matched = pattern.match(normalized)
+            if matched is None:
+                continue
+            params = {
+                name: matched.group(name)
+                for name in names
+                if matched.group(name) is not None
+            }
+            return meta_index, params
+
+        raise KeyError((m, normalized))
+
+    def __call__(self, method: str, path: str) -> tuple[int, dict[str, str]]:
+        return self.match(method, path)
+
+    # Compatibility mapping surface used by older tests and adapters.
+    def __contains__(self, selector: object) -> bool:
+        return isinstance(selector, str) and selector in self._selectors
+
+    def __getitem__(self, selector: str) -> int:
+        return self._selectors[selector]
+
+    def get(self, selector: str, default: Any = None) -> Any:
+        return self._selectors.get(selector, default)
+
+    def keys(self):
+        return self._selectors.keys()
+
+    def items(self):
+        return self._selectors.items()
+
+    def values(self):
+        return self._selectors.values()
+
+    def __iter__(self):
+        return iter(self._selectors)
+
+    def __len__(self) -> int:
+        return len(self._selectors)
+
+
+def deepmerge_phase_chains(
+    *phase_maps: Mapping[str, Sequence[StepFn]],
+) -> Dict[str, List[StepFn]]:
+    """Deterministically concatenate phase step lists into a new mapping."""
+    merged: Dict[str, List[StepFn]] = {}
+    for phase_map in phase_maps:
+        for phase, steps in (phase_map or {}).items():
+            merged.setdefault(phase, []).extend(list(steps or ()))
+    return {phase: list(steps) for phase, steps in merged.items()}
+
+
+def _table_iter(app: Any) -> Sequence[type]:
+    tables = getattr(app, "tables", None)
+    if isinstance(tables, dict):
+        return tuple(v for v in tables.values() if isinstance(v, type))
+    return ()
+
+
+def _opspecs(model: type) -> Sequence[Any]:
+    return getattr(getattr(model, "opspecs", SimpleNamespace()), "all", ()) or ()
+
+
+def _label_callable(fn: Any) -> str:
+    name = getattr(fn, "__qualname__", getattr(fn, "__name__", repr(fn)))
+    module = getattr(fn, "__module__", None)
+    return f"{module}.{name}" if module else name
+
+
+def _label_step(step: Any, phase: str) -> str:
+    label = getattr(step, "__tigrbl_label", None)
+    if isinstance(label, str) and "@" in label:
+        return label
+    module = getattr(step, "__module__", "") or ""
+    name = getattr(step, "__name__", "") or ""
+    if module.startswith("tigrbl_core.core.crud") and name:
+        return f"hook:wire:tigrbl:core:crud:ops:{name}@{phase}"
+    return f"hook:wire:{_label_callable(step).replace('.', ':')}@{phase}"
+
+
+class Kernel:
+    """
+    SSoT for runtime scheduling. One Kernel per App (not per API).
+    Auto-primed under the hood. Downstream users never touch this.
+    """
+
+    _instance: ClassVar["Kernel | None"] = None
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> "Kernel":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self, atoms: Optional[Sequence[_DiscoveredAtom]] = None):
+        if atoms is None and getattr(self, "_singleton_initialized", False):
+            self._reset(atoms)
+            return
+        self._reset(atoms)
+        if atoms is None:
+            self._singleton_initialized = True
+
+    def _reset(self, atoms: Optional[Sequence[_DiscoveredAtom]] = None) -> None:
+        self._atoms_cache = list(atoms) if atoms else None
+        self._specs_cache = _SpecsOnceCache()
+        self._opviews = _WeakMaybeDict()
+        self._kernel_plans = _WeakMaybeDict()
+        self._kernelz_payload = _WeakMaybeDict()
+        self._primed = _WeakMaybeDict()
+        self._lock = threading.Lock()
+
+    def _atoms(self) -> list[_DiscoveredAtom]:
+        if self._atoms_cache is None:
+            self._atoms_cache = _discover_atoms()
+        return self._atoms_cache
+
+    def get_specs(self, model: type) -> Mapping[str, Any]:
+        return self._specs_cache.get(model)
+
+    def _compile_opview_from_specs(self, specs: Mapping[str, Any], sp: Any) -> OpView:
+        """Compatibility shim for callers using legacy Kernel method dispatch."""
+        return compile_opview_from_specs(specs, sp)
+
+    def prime_specs(self, models: Sequence[type]) -> None:
+        self._specs_cache.prime(models)
+
+    def invalidate_specs(self, model: Optional[type] = None) -> None:
+        self._specs_cache.invalidate(model)
+
+    def build_op(self, model: type, alias: str) -> Dict[str, List[StepFn]]:
+        chains = _hook_phase_chains(model, alias)
+        specs = getattr(getattr(model, "ops", SimpleNamespace()), "by_alias", {})
+        sp_list = specs.get(alias) or ()
+        sp = sp_list[0] if sp_list else 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)
+
+        try:
+            _inject_atoms(chains, self._atoms() or (), persistent=persistent)
+        except Exception:
+            logger.exception(
+                "kernel: atom injection failed for %s.%s",
+                getattr(model, "__name__", model),
+                alias,
+            )
+
+        _inject_pre_tx_dep_atoms(chains, sp)
+
+        if persistent:
+            try:
+                _inject_txn_system_steps(chains, model=model)
+            except Exception:
+                logger.exception(
+                    "kernel: failed to inject txn system steps for %s.%s",
+                    getattr(model, "__name__", model),
+                    alias,
+                )
+        for phase in _ev.PHASES:
+            chains.setdefault(phase, [])
+        return chains
+
+    def build(self, model: type, alias: str) -> Dict[str, List[StepFn]]:
+        return self.build_op(model, alias)
+
+    def build_ingress(self, app: Any) -> Dict[str, List[StepFn]]:
+        del app
+        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 not _ev.is_valid_event(anchor):
+                continue
+            phase = _ev.phase_for_event(anchor)
+            if phase not in {"INGRESS_BEGIN", "INGRESS_PARSE", "INGRESS_ROUTE"}:
+                continue
+            ingress_atoms.setdefault(phase, []).append((anchor, run))
+
+        out: Dict[str, List[StepFn]] = {}
+        for phase, atoms in ingress_atoms.items():
+            ordered = sorted(atoms, key=lambda item: order.get(item[0], 10_000))
+            out[phase] = [_wrap_atom(run, anchor=anchor) for anchor, run in ordered]
+        return out
+
+    def build_egress(self, app: Any) -> Dict[str, List[StepFn]]:
+        del app
+        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 not _ev.is_valid_event(anchor):
+                continue
+            phase = _ev.phase_for_event(anchor)
+            if phase not in {"EGRESS_SHAPE", "EGRESS_FINALIZE", "POST_RESPONSE"}:
+                continue
+            egress_atoms.setdefault(phase, []).append((anchor, run))
+
+        out: Dict[str, List[StepFn]] = {}
+        for phase, atoms in egress_atoms.items():
+            ordered = sorted(atoms, key=lambda item: order.get(item[0], 10_000))
+            out[phase] = [_wrap_atom(run, anchor=anchor) for anchor, run in ordered]
+        return out
+
+    def plan_labels(self, model: type, alias: str) -> list[str]:
+        labels: list[str] = []
+        chains = self.build(model, alias)
+        opspec = next(
+            (sp for sp in _opspecs(model) if getattr(sp, "alias", None) == alias),
+            None,
+        )
+        persist = getattr(opspec, "persist", "default") != "skip"
+
+        tx_begin = "START_TX:hook:sys:txn:begin@START_TX"
+        tx_end = "END_TX:hook:sys:txn:commit@END_TX"
+        if persist:
+            labels.append(tx_begin)
+
+        for phase in _ev.PHASES:
+            if phase in {
+                "INGRESS_BEGIN",
+                "INGRESS_PARSE",
+                "INGRESS_ROUTE",
+                "EGRESS_SHAPE",
+                "EGRESS_FINALIZE",
+                "START_TX",
+                "END_TX",
+            }:
+                continue
+            for step in chains.get(phase, ()) or ():
+                labels.append(f"{phase}:{label_hook(step, phase)}")
+
+        if persist:
+            labels.append(tx_end)
+
+        return labels
+
+    async def invoke(
+        self,
+        *,
+        model: type,
+        alias: str,
+        db: Any,
+        request: Any | None = None,
+        ctx: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        """Execute an operation for ``model.alias`` using the executor."""
+        phases = self.build_op(model, alias)
+        base_ctx = _Ctx.ensure(request=request, db=db, seed=ctx)
+        base_ctx.model = model
+        base_ctx.op = alias
+        specs = self.get_specs(model)
+        base_ctx.opview = compile_opview_from_specs(specs, SimpleNamespace(alias=alias))
+        return await _invoke(request=request, db=db, phases=phases, ctx=base_ctx)
+
+    def ensure_primed(self, app: Any) -> None:
+        """Autoprime once per App: specs → OpViews → /kernelz payload."""
+        with self._lock:
+            if self._primed.get(app):
+                return
+            models = list(_table_iter(app))
+            for model in models:
+                self._specs_cache.get(model)
+
+            ov_map: Dict[Tuple[type, str], OpView] = {}
+            for model in models:
+                specs = self._specs_cache.get(model)
+                for sp in _opspecs(model):
+                    ov_map[(model, sp.alias)] = compile_opview_from_specs(specs, sp)
+            self._opviews[app] = ov_map
+
+            self._kernelz_payload[app] = self.compile_plan(app)
+            self._primed[app] = True
+
+    def get_opview(self, app: Any, model: type, alias: str) -> OpView:
+        """Return OpView for (model, alias); compile on-demand if missing."""
+        ov_map = self._opviews.get(app)
+        if isinstance(ov_map, dict):
+            opview = ov_map.get((model, alias))
+            if opview is not None:
+                return opview
+
+        self.ensure_primed(app)
+
+        ov_map = self._opviews.setdefault(app, {})
+        opview = ov_map.get((model, alias))
+        if opview is not None:
+            return opview
+
+        try:
+            specs = self._specs_cache.get(model)
+            found = False
+            for sp in _opspecs(model):
+                ov_map.setdefault(
+                    (model, sp.alias), compile_opview_from_specs(specs, sp)
+                )
+                if sp.alias == alias:
+                    found = True
+
+            if not found:
+                temp_sp = SimpleNamespace(alias=alias)
+                ov_map[(model, alias)] = compile_opview_from_specs(specs, temp_sp)
+
+            return ov_map[(model, alias)]
+        except Exception as exc:
+            raise RuntimeError(
+                f"opview_missing: app={app!r} model={getattr(model, '__name__', model)!r} alias={alias!r}"
+            ) from exc
+
+    async def _run_phase_chain(self, ctx: _Ctx, phases: Any) -> None:
+        for _phase, steps in (phases or {}).items():
+            for step in steps or ():
+                rv = step(ctx)
+                if hasattr(rv, "__await__"):
+                    await rv
+
+    @staticmethod
+    def _without_ingress_phases(phases: Mapping[str, Any] | None) -> dict[str, Any]:
+        if not phases:
+            return {}
+        ingress = {"INGRESS_BEGIN", "INGRESS_PARSE", "INGRESS_ROUTE"}
+        return {phase: steps for phase, steps in phases.items() if phase not in ingress}
+
+    async def handle_http(self, env: Any, app: Any) -> None:
+        from tigrbl_canon.mapping.runtime_routes import invoke_runtime_route_handler
+        from tigrbl_concrete.atoms.egress.asgi_send import (
+            _send_json,
+            _send_transport_response,
+        )
+        from tigrbl_runtime.status import StatusDetailError
+
+        plan = self.kernel_plan(app)
+        ctx = _Ctx.ensure(request=None, db=None)
+        ctx.app = app
+        ctx.router = app
+        ctx.raw = env
+        ctx.kernel_plan = plan
+
+        await self._run_phase_chain(ctx, plan.ingress_chain)
+
+        route = (
+            ctx.temp.get("route", {})
+            if isinstance(getattr(ctx, "temp", None), dict)
+            else {}
+        )
+        egress = (
+            ctx.temp.get("egress", {})
+            if isinstance(getattr(ctx, "temp", None), dict)
+            else {}
+        )
+        if (
+            isinstance(route, dict)
+            and route.get("short_circuit") is True
+            and isinstance(egress, dict)
+            and egress.get("transport_response")
+        ):
+            await _send_transport_response(env, ctx)
+            return
+
+        opmeta_index = route.get("opmeta_index") if isinstance(route, dict) else None
+        if not isinstance(opmeta_index, int):
+            if isinstance(route, dict) and route.get("method_not_allowed") is True:
+                await _send_json(env, 405, {"detail": "Method Not Allowed"})
+                return
+            handler = route.get("handler") if isinstance(route, dict) else None
+            if callable(handler):
+                await invoke_runtime_route_handler(ctx, handler=handler)
+                await _send_transport_response(env, ctx)
+                return
+            await _send_json(
+                env, 404, {"detail": "No runtime operation matched request."}
+            )
+            return
+
+        opmeta = plan.opmeta[opmeta_index]
+        ctx.model = opmeta.model
+        ctx.op = opmeta.alias
+        ctx.opview = self.get_opview(app, opmeta.model, opmeta.alias)
+
+        phases = self._without_ingress_phases(plan.phase_chains.get(opmeta_index, {}))
+        try:
+            await _invoke(request=None, db=None, phases=phases, ctx=ctx)
+        except StatusDetailError as exc:
+            detail = (
+                exc.detail
+                if getattr(exc, "detail", None) not in (None, "")
+                else str(exc)
+            )
+            await _send_json(
+                env, int(getattr(exc, "status_code", 500) or 500), {"detail": detail}
+            )
+            return
+        except Exception as exc:  # pragma: no cover - defensive runtime fallback
+            from tigrbl_runtime.status import create_standardized_error
+
+            std = create_standardized_error(exc)
+            detail = (
+                std.detail
+                if getattr(std, "detail", None) not in (None, "")
+                else str(std)
+            )
+            await _send_json(
+                env, int(getattr(std, "status_code", 500) or 500), {"detail": detail}
+            )
+            return
+
+        await _send_transport_response(env, ctx)
+
+    def compile_plan(self, app: Any) -> KernelPlan:
+        from tigrbl_core._spec.binding_spec import (
+            HttpJsonRpcBindingSpec,
+            HttpRestBindingSpec,
+            WsBindingSpec,
+        )
+
+        proto_indices: dict[str, Any] = {"http.rest": {}, "https.rest": {}}
+        opmeta: list[OpMeta] = []
+        opkey_to_meta: dict[OpKey, int] = {}
+        phase_chains: dict[int, Mapping[str, list[StepFn]]] = {}
+        ingress_chain = self.build_ingress(app)
+        egress_chain = self.build_egress(app)
+
+        for model in _table_iter(app):
+            for sp in _opspecs(model):
+                meta_index = len(opmeta)
+                target = (getattr(sp, "target", sp.alias) or sp.alias).lower()
+                opmeta.append(OpMeta(model=model, alias=sp.alias, target=target))
+                phase_chains[meta_index] = deepmerge_phase_chains(
+                    ingress_chain,
+                    self.build_op(model, sp.alias),
+                    egress_chain,
+                )
+
+                for binding in getattr(sp, "bindings", ()) or ():
+                    if isinstance(binding, HttpRestBindingSpec):
+                        for method in binding.methods:
+                            selector = f"{method.upper()} {binding.path}"
+                            opkey = OpKey(proto=binding.proto, selector=selector)
+                            opkey_to_meta[opkey] = meta_index
+                            proto_indices.setdefault(binding.proto, {})[selector] = (
+                                meta_index
+                            )
+                    elif isinstance(binding, HttpJsonRpcBindingSpec):
+                        opkey = OpKey(proto=binding.proto, selector=binding.rpc_method)
+                        opkey_to_meta[opkey] = meta_index
+                        proto_indices.setdefault(binding.proto, {})[
+                            binding.rpc_method
+                        ] = meta_index
+                    elif isinstance(binding, WsBindingSpec):
+                        selector = binding.path
+                        if binding.subprotocols:
+                            for subprotocol in binding.subprotocols:
+                                full_selector = f"{selector}|{subprotocol}"
+                                opkey = OpKey(
+                                    proto=binding.proto, selector=full_selector
+                                )
+                                opkey_to_meta[opkey] = meta_index
+                                proto_indices.setdefault(binding.proto, {})[
+                                    full_selector
+                                ] = meta_index
+                        else:
+                            opkey = OpKey(proto=binding.proto, selector=selector)
+                            opkey_to_meta[opkey] = meta_index
+                            proto_indices.setdefault(binding.proto, {})[selector] = (
+                                meta_index
+                            )
+
+        return KernelPlan(
+            proto_indices=proto_indices,
+            opmeta=tuple(opmeta),
+            opkey_to_meta=opkey_to_meta,
+            ingress_chain=ingress_chain,
+            phase_chains=phase_chains,
+            egress_chain=egress_chain,
+        )
+
+    def compile_bootstrap_plan(self, app: Any) -> Dict[str, List[StepFn]]:
+        """Compatibility entrypoint for ingress-only bootstrap diagnostics."""
+        return self.build_ingress(app)
+
+    def kernel_plan(self, app: Any) -> KernelPlan:
+        self.ensure_primed(app)
+        plan = self._kernel_plans.get(app)
+        if isinstance(plan, KernelPlan):
+            return plan
+
+        compiled = self.compile_plan(app)
+        self._kernel_plans[app] = compiled
+
+        payload: dict[str, dict[str, list[str]]] = {}
+        for model in _table_iter(app):
+            model_name = getattr(model, "__name__", str(model))
+            payload[model_name] = {}
+            for sp in _opspecs(model):
+                payload[model_name][sp.alias] = self.plan_labels(model, sp.alias)
+        self._kernelz_payload[app] = payload
+
+        return compiled
+
+    def kernelz_payload(self, app: Any) -> dict[str, dict[str, list[str]]]:
+        """Thin accessor for endpoint: guarantees primed diagnostics payload."""
+        self.kernel_plan(app)
+        payload = self._kernelz_payload.get(app)
+        if isinstance(payload, dict):
+            return payload
+        return {}
+
+    def invalidate_kernelz_payload(self, app: Optional[Any] = None) -> None:
+        with self._lock:
+            if app is None:
+                self._kernel_plans = _WeakMaybeDict()
+                self._kernelz_payload = _WeakMaybeDict()
+                self._opviews = _WeakMaybeDict()
+                self._primed = _WeakMaybeDict()
+            else:
+                self._kernel_plans.pop(app, None)
+                self._kernelz_payload.pop(app, None)
+                self._opviews.pop(app, None)
+                self._primed.pop(app, None)

tigrbl_kernel/kernel/models.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Iterator, Mapping, Tuple
+
+
+def _label_callable(fn: Any) -> str:
+    name = getattr(fn, "__qualname__", getattr(fn, "__name__", repr(fn)))
+    module = getattr(fn, "__module__", None)
+    return f"{module}.{name}" if module else name
+
+
+def _label_step(step: Any, phase: str) -> str:
+    label = getattr(step, "__tigrbl_label", None)
+    if isinstance(label, str) and "@" in label:
+        return label
+    module = getattr(step, "__module__", "") or ""
+    name = getattr(step, "__name__", "") or ""
+    if module.startswith("tigrbl_core.core.crud") and name:
+        return f"hook:wire:tigrbl:core:crud:ops:{name}@{phase}"
+    return f"hook:wire:{_label_callable(step).replace('.', ':')}@{phase}"
+
+
+@dataclass(frozen=True)
+class SchemaIn:
+    fields: Tuple[str, ...]
+    by_field: Dict[str, Dict[str, object]]
+
+
+@dataclass(frozen=True)
+class SchemaOut:
+    fields: Tuple[str, ...]
+    by_field: Dict[str, Dict[str, object]]
+    expose: Tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class OpView:
+    schema_in: SchemaIn
+    schema_out: SchemaOut
+    paired_index: Dict[str, Dict[str, object]]
+    virtual_producers: Dict[str, Callable[[object, dict], object]]
+    to_stored_transforms: Dict[str, Callable[[object, dict], object]]
+    refresh_hints: Tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class OpKey:
+    proto: str
+    selector: str
+
+
+@dataclass(frozen=True, slots=True)
+class OpMeta:
+    model: type
+    alias: str
+    target: str
+
+
+@dataclass(frozen=True, slots=True)
+class KernelPlan:
+    proto_indices: Mapping[str, Any] = field(default_factory=dict)
+    opmeta: tuple[OpMeta, ...] = ()
+    opkey_to_meta: Mapping[OpKey, int] = field(default_factory=dict)
+    ingress_chain: Mapping[str, list[Callable[..., Any]]] = field(default_factory=dict)
+    phase_chains: Mapping[int, Mapping[str, list[Callable[..., Any]]]] = field(
+        default_factory=dict
+    )
+    egress_chain: Mapping[str, list[Callable[..., Any]]] = field(default_factory=dict)
+    _appspec_mapping: Dict[str, Dict[str, list[str]]] = field(
+        default_factory=dict, init=False, repr=False, compare=False
+    )
+
+    def _normalize_mappings(self) -> Dict[str, Dict[str, list[str]]]:
+        if self._appspec_mapping:
+            return self._appspec_mapping
+
+        from tigrbl_runtime import events as _ev
+
+        normalized: Dict[str, Dict[str, list[str]]] = {}
+        for meta_index, meta in enumerate(self.opmeta):
+            table_name = getattr(meta.model, "__name__", str(meta.model))
+            labels: list[str] = []
+            chains = self.phase_chains.get(meta_index, {})
+            for phase in _ev.PHASES:
+                phase_steps = chains.get(phase, ())
+                for step in phase_steps or ():
+                    labels.append(_label_step(step, phase))
+
+            seen, deduped = set(), []
+            for label in labels:
+                if ":hook:wire:" in label:
+                    if label in seen:
+                        continue
+                    seen.add(label)
+                deduped.append(label)
+
+            normalized.setdefault(table_name, {})[meta.alias] = deduped
+
+        self._appspec_mapping.update(normalized)
+        return self._appspec_mapping
+
+    def __getitem__(self, key: str) -> Dict[str, list[str]]:
+        return self._normalize_mappings()[key]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._normalize_mappings())
+
+    def __len__(self) -> int:
+        return len(self._normalize_mappings())
+
+    def get(
+        self, key: str, default: Dict[str, list[str]] | None = None
+    ) -> Dict[str, list[str]] | None:
+        return self._normalize_mappings().get(key, default)
+
+    def items(self):
+        return self._normalize_mappings().items()
+
+    def keys(self):
+        return self._normalize_mappings().keys()
+
+    def values(self):
+        return self._normalize_mappings().values()

tigrbl_kernel/kernel/opview_compiler.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping
+
+from .models import OpView, SchemaIn, SchemaOut
+
+
+def compile_opview_from_specs(specs: Mapping[str, Any], sp: Any) -> OpView:
+    """Build a basic OpView from collected specs when no app/model is present."""
+    alias = getattr(sp, "alias", "")
+
+    in_fields: list[str] = []
+    out_fields: list[str] = []
+    by_field_in: Dict[str, Dict[str, object]] = {}
+    by_field_out: Dict[str, Dict[str, object]] = {}
+
+    for name, spec in specs.items():
+        io = getattr(spec, "io", None)
+        fs = getattr(spec, "field", None)
+        storage = getattr(spec, "storage", None)
+        in_verbs = set(getattr(io, "in_verbs", ()) or ())
+        out_verbs = set(getattr(io, "out_verbs", ()) or ())
+
+        if alias in in_verbs:
+            in_fields.append(name)
+            meta: Dict[str, object] = {"in_enabled": True}
+            if storage is None:
+                meta["virtual"] = True
+            default_factory = getattr(spec, "default_factory", None)
+            if callable(default_factory):
+                meta["default_factory"] = default_factory
+            alias_in = getattr(io, "alias_in", None)
+            if alias_in:
+                meta["alias_in"] = alias_in
+            header_in = getattr(io, "header_in", None)
+            if header_in:
+                meta["header_in"] = header_in
+                meta["header_required_in"] = bool(
+                    getattr(io, "header_required_in", False)
+                )
+            required = bool(fs and alias in getattr(fs, "required_in", ()))
+            meta["required"] = required
+            base_nullable = (
+                True if storage is None else getattr(storage, "nullable", True)
+            )
+            meta["nullable"] = base_nullable
+            by_field_in[name] = meta
+
+        if alias in out_verbs:
+            out_fields.append(name)
+            meta_out: Dict[str, object] = {}
+            alias_out = getattr(io, "alias_out", None)
+            if alias_out:
+                meta_out["alias_out"] = alias_out
+            if storage is None:
+                meta_out["virtual"] = True
+            py_type = getattr(getattr(fs, "py_type", None), "__name__", None)
+            if py_type:
+                meta_out["py_type"] = py_type
+            by_field_out[name] = meta_out
+
+    schema_in = SchemaIn(
+        fields=tuple(sorted(in_fields)),
+        by_field={field: by_field_in.get(field, {}) for field in sorted(in_fields)},
+    )
+    schema_out = SchemaOut(
+        fields=tuple(sorted(out_fields)),
+        by_field={field: by_field_out.get(field, {}) for field in sorted(out_fields)},
+        expose=tuple(sorted(out_fields)),
+    )
+    paired_index: Dict[str, Dict[str, object]] = {}
+    for field, col in specs.items():
+        io = getattr(col, "io", None)
+        cfg = getattr(io, "_paired", None)
+        if cfg and alias in getattr(cfg, "verbs", ()):  # type: ignore[attr-defined]
+            field_spec = getattr(col, "field", None)
+            max_length = None
+            if field_spec is not None:
+                max_length = getattr(
+                    getattr(field_spec, "constraints", {}),
+                    "get",
+                    lambda k, d=None: None,
+                )("max_length")
+            paired_index[field] = {
+                "alias": cfg.alias,
+                "gen": cfg.gen,
+                "store": cfg.store,
+                "mask_last": cfg.mask_last,
+                "max_length": max_length,
+            }
+
+    return OpView(
+        schema_in=schema_in,
+        schema_out=schema_out,
+        paired_index=paired_index,
+        virtual_producers={},
+        to_stored_transforms={},
+        refresh_hints=(),
+    )

tigrbl_kernel/kernel/payload.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from tigrbl_runtime import events as _ev
+from tigrbl_runtime.labels import label_hook
+
+
+def _callable_label(fn: Any) -> str:
+    module = getattr(fn, "__module__", "") or ""
+    qualname = getattr(fn, "__qualname__", getattr(fn, "__name__", repr(fn)))
+    return f"{module}.{qualname}" if module else qualname
+
+
+if TYPE_CHECKING:
+    from .core import Kernel
+
+
+def _table_iter(app: Any):
+    tables = getattr(app, "tables", None)
+    if isinstance(tables, dict):
+        return tuple(v for v in tables.values() if isinstance(v, type))
+    return ()
+
+
+def _opspecs(model: type):
+    return getattr(getattr(model, "opspecs", object()), "all", ()) or ()
+
+
+def build_kernelz_payload(kernel: "Kernel", app: Any):
+    payload: dict[str, dict[str, list[str]]] = {}
+    for model in _table_iter(app):
+        mname = getattr(model, "__name__", str(model))
+        payload[mname] = {}
+        for sp in _opspecs(model):
+            labels: list[str] = []
+            for dep in getattr(sp, "secdeps", ()) or ():
+                labels.append(
+                    f"PRE_TX_BEGIN:hook:dep:security:{_callable_label(getattr(dep, 'dependency', dep))}"
+                )
+            for dep in getattr(sp, "deps", ()) or ():
+                labels.append(
+                    f"PRE_TX_BEGIN:hook:dep:extra:{_callable_label(getattr(dep, 'dependency', dep))}"
+                )
+
+            persist = getattr(sp, "persist", "default") != "skip"
+            if persist:
+                labels.append("START_TX:hook:sys:txn:begin@START_TX")
+
+            chains = kernel.build(model, sp.alias)
+            for phase in _ev.PHASES:
+                if phase in {"START_TX", "END_TX", "PRE_TX_BEGIN", "POST_RESPONSE"}:
+                    continue
+                for step in chains.get(phase, ()) or ():
+                    labels.append(f"{phase}:{label_hook(step, phase)}")
+
+            if persist:
+                labels.append("END_TX:hook:sys:txn:commit@END_TX")
+
+            for step in chains.get("POST_RESPONSE", ()) or ():
+                labels.append(f"POST_RESPONSE:{label_hook(step, 'POST_RESPONSE')}")
+
+            payload[mname][sp.alias] = labels
+    return payload

tigrbl_kernel-0.1.0.dev1.dist-info/METADATA

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: tigrbl-kernel
+Version: 0.1.0.dev1
+Summary: Kernel orchestration for Tigrbl runtime composition.
+License-Expression: Apache-2.0
+Keywords: tigrbl,sdk,standards,framework
+Author: Jacob Stewart
+Author-email: jacob@swarmauri.com
+Requires-Python: >=3.10,<3.13
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Development Status :: 1 - Planning
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Dist: tigrbl-atoms
+Requires-Dist: tigrbl-canon
+Description-Content-Type: text/markdown
+
+![Tigrbl branding](https://github.com/swarmauri/swarmauri-sdk/blob/a170683ecda8ca1c4f912c966d4499649ffb8224/assets/tigrbl.brand.theme.svg)
+
+# tigrbl-kernel
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/tigrbl-kernel.svg) ![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg) ![Python Versions](https://img.shields.io/pypi/pyversions/tigrbl-kernel.svg) ![License](https://img.shields.io/pypi/l/tigrbl-kernel.svg) ![Version](https://img.shields.io/pypi/v/tigrbl-kernel.svg)
+
+## Features
+
+- Modular package in the Tigrbl namespace.
+- Supports Python 3.10 through 3.12.
+- Distributed as part of the swarmauri-sdk workspace.
+
+## Installation
+
+### uv
+
+```bash
+uv add tigrbl-kernel
+```
+
+### pip
+
+```bash
+pip install tigrbl-kernel
+```
+
+## Usage
+
+Import from the shared package-specific module namespaces after installation in your environment.
+

tigrbl_kernel-0.1.0.dev1.dist-info/RECORD

@@ -0,0 +1,10 @@
+tigrbl_kernel/kernel/__init__.py,sha256=Vnd3I9czWwQAAdCCKPEuDdg3xnZafSPXruLaXCRkFOU,1215
+tigrbl_kernel/kernel/atoms.py,sha256=aaTOixPocG1Hxn5JJ3Ww-vH63aWSyoKzidz0ojXwypk,7308
+tigrbl_kernel/kernel/cache.py,sha256=IBhLUsHo8ASlnQXGGbw9MoQYaOpID7YBBcLNfIjA-uE,2606
+tigrbl_kernel/kernel/core.py,sha256=bstWeuJYhNgucOkzH9BVgnQC7I5ZkN1L99pH2Gxx1VY,22142
+tigrbl_kernel/kernel/models.py,sha256=l31lxLk4_0-pUyiHLTojYYhhlD6VuPLiC7-iIqKCfoc,3983
+tigrbl_kernel/kernel/opview_compiler.py,sha256=KDBllYxk-gqyohLWMKbNSo135mKMzsQgeitYdJJJJ-o,3738
+tigrbl_kernel/kernel/payload.py,sha256=ofg0ejCtO5VICsXxrfT2UiT9SaGHSrbr-G49avqCiLo,2236
+tigrbl_kernel-0.1.0.dev1.dist-info/METADATA,sha256=kKOzoqErirX14gzGVLDNzhPtAR17QqAeRno_EzryjFE,1642
+tigrbl_kernel-0.1.0.dev1.dist-info/WHEEL,sha256=kJCRJT_g0adfAJzTx2GUMmS80rTJIVHRCfG0DQgLq3o,88
+tigrbl_kernel-0.1.0.dev1.dist-info/RECORD,,

tigrbl_kernel-0.1.0.dev1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.1
+Root-Is-Purelib: true
+Tag: py3-none-any