hypermind 0.11.0__py3-none-any.whl

hypermind/sync.py

@@ -0,0 +1,191 @@
+"""Synchronous wrapper around :class:`hypermind.HyperMindAgent`.
+
+Some integrators (notebooks, CLIs, simple scripts) cannot or do not
+want to use ``async``/``await``. ``SyncAgent`` is a thin wrapper that
+exposes every public async verb of ``HyperMindAgent`` as a sync method.
+
+Implementation strategy (Jupyter-safe):
+
+  * If the calling thread already has a running event loop (e.g. inside
+    a Jupyter cell), ``SyncAgent`` lazily spawns a dedicated worker
+    thread that owns its own ``asyncio.new_event_loop()`` and uses
+    ``asyncio.run_coroutine_threadsafe`` to dispatch coroutines to it.
+  * Otherwise, ``asyncio.run`` is used per call.
+
+The wrapper is generated by **introspection** — every ``async def``
+public method on :class:`HyperMindAgent` is auto-wrapped, so there is
+nothing to keep in sync by hand. Sync property/passthrough access for
+non-async helpers (``working_memory``, ``advance_time``, etc.) is also
+forwarded.
+
+ROADMAP §0.5.7. Stable from v0.5; signatures track ``HyperMindAgent``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import threading
+from typing import TYPE_CHECKING, Any
+
+from hypermind.agent import HyperMindAgent
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Coroutine
+
+
+# ---------------------------------------------------------------------
+# Module-level worker loop (Jupyter-safe path).
+# ---------------------------------------------------------------------
+
+_worker_lock = threading.Lock()
+_worker_loop: asyncio.AbstractEventLoop | None = None
+_worker_thread: threading.Thread | None = None
+
+
+def _ensure_worker_loop() -> asyncio.AbstractEventLoop:
+    """Lazily start the dedicated worker thread + loop.
+
+    The worker is daemonised so it does not block interpreter shutdown.
+    """
+    global _worker_loop, _worker_thread
+    with _worker_lock:
+        if _worker_loop is not None and _worker_thread is not None and _worker_thread.is_alive():
+            return _worker_loop
+        loop = asyncio.new_event_loop()
+        ready = threading.Event()
+
+        def _run() -> None:
+            asyncio.set_event_loop(loop)
+            ready.set()
+            loop.run_forever()
+
+        thread = threading.Thread(target=_run, name="hypermind-sync-worker", daemon=True)
+        thread.start()
+        ready.wait()
+        _worker_loop = loop
+        _worker_thread = thread
+        return loop
+
+
+def _run_coro(coro: Coroutine[Any, Any, Any]) -> Any:
+    """Run a coroutine to completion from a synchronous context.
+
+    If the current thread already has a running loop (Jupyter), schedule
+    on the worker loop via ``run_coroutine_threadsafe``; otherwise use
+    ``asyncio.run``.
+    """
+    try:
+        asyncio.get_running_loop()
+        running_loop = True
+    except RuntimeError:
+        running_loop = False
+    if running_loop:
+        loop = _ensure_worker_loop()
+        fut = asyncio.run_coroutine_threadsafe(coro, loop)
+        return fut.result()
+    return asyncio.run(coro)
+
+
+# ---------------------------------------------------------------------
+# SyncAgent
+# ---------------------------------------------------------------------
+
+
+class SyncAgent:
+    """Synchronous wrapper around a single :class:`HyperMindAgent`.
+
+    Every public ``async def`` method of ``HyperMindAgent`` is exposed
+    as a sync method here with the same signature minus the ``async``.
+    Non-async public attributes (e.g. ``working_memory``, ``namespace``,
+    ``rooms``) are forwarded through ``__getattr__``.
+
+    Use :meth:`SyncAgent.sandbox` or :meth:`SyncAgent.testbed_cohort` to
+    construct.
+    """
+
+    __slots__ = ("_agent",)
+
+    def __init__(self, agent: HyperMindAgent) -> None:
+        object.__setattr__(self, "_agent", agent)
+
+    # ---- factories -----------------------------------------------------
+
+    @classmethod
+    def sandbox(cls, **kwargs: Any) -> SyncAgent:
+        """Sync analogue of :meth:`HyperMindAgent.sandbox`."""
+        return cls(HyperMindAgent.sandbox(**kwargs))
+
+    @classmethod
+    def testbed_cohort(cls, n: int = 2, **kwargs: Any) -> list[SyncAgent]:
+        """Sync analogue of :func:`hypermind.testing.testbed_cohort`.
+
+        Returns a plain list of wrapped agents. Caller is responsible for
+        calling :meth:`close` (or using :class:`contextlib.ExitStack`) —
+        there is no async-with cleanup in the sync surface.
+        """
+        agents = HyperMindAgent.testbed(agents=n, **kwargs)
+        return [cls(a) for a in agents]
+
+    # ---- context-manager passthrough ----------------------------------
+
+    def __enter__(self) -> SyncAgent:
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+    # ---- forwarded attribute access -----------------------------------
+
+    def __getattr__(self, name: str) -> Any:
+        # Avoid recursion on lookup of private slot.
+        if name == "_agent":
+            raise AttributeError(name)
+        agent = object.__getattribute__(self, "_agent")
+        attr = getattr(agent, name)
+        if inspect.iscoroutinefunction(attr):
+
+            def _sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                return _run_coro(attr(*args, **kwargs))
+
+            _sync_wrapper.__name__ = name
+            _sync_wrapper.__doc__ = attr.__doc__
+            return _sync_wrapper
+        if inspect.isasyncgenfunction(attr):
+            # Drain an async generator into a synchronous list. For
+            # truly streaming outputs, callers SHOULD stay on
+            # ``HyperMindAgent`` and the async path; the sync surface
+            # materialises the full sequence in memory.
+            def _sync_drain(*args: Any, **kwargs: Any) -> list[Any]:
+                async def _collect() -> list[Any]:
+                    out: list[Any] = []
+                    async for item in attr(*args, **kwargs):
+                        out.append(item)
+                    return out
+
+                return _run_coro(_collect())
+
+            _sync_drain.__name__ = name
+            _sync_drain.__doc__ = attr.__doc__
+            return _sync_drain
+        return attr
+
+
+# ---------------------------------------------------------------------
+# Verb-parity assertion (introspection-driven test surface).
+# ---------------------------------------------------------------------
+
+
+def _public_async_verbs(cls: type) -> list[str]:
+    """Return sorted names of public ``async def`` (or async-generator)
+    methods of ``cls``."""
+    out: list[str] = []
+    for name, member in inspect.getmembers(cls):
+        if name.startswith("_"):
+            continue
+        if inspect.iscoroutinefunction(member) or inspect.isasyncgenfunction(member):
+            out.append(name)
+    return sorted(out)
+
+
+__all__ = ["SyncAgent", "_public_async_verbs"]

hypermind/tal.py

@@ -0,0 +1,175 @@
+"""Trust & Access Layer (TAL) — reputation-gated Rooms with vouch decay.
+
+Implements the application-layer membership control described in
+``docs/spec/07-trust-access-layer.md``: Rooms with a per-Room minimum
+reputation, vouches with HLC timestamps, and exponential decay applied
+to old vouch contributions.
+
+This module is the v0.1 surface — a minimal subset of §7 sufficient to
+gate ``discover_mentors`` / ``request_vouch`` and unblock the federated
+learning loop. The full §7 wire messages (ROOM_DEFINE, ROOM_JOIN,
+VOUCH, VOUCH_REVOKE) land in v0.2.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from hypermind.knowledge.reputation import ReputationKernel
+
+
+class TALError(Exception):
+    """Raised when a TAL operation violates a Room policy."""
+
+
+@dataclass
+class Room:
+    room_id: str
+    min_reputation: float  # 0.0 = open
+    members: set[bytes] = field(default_factory=set)
+    creator_kid: bytes = b""
+
+
+@dataclass
+class TrustStatus:
+    in_room: bool
+    reputation_snapshot: float
+    vouch_count: int
+
+
+@dataclass
+class _VouchRecord:
+    voucher_kid: bytes
+    vouchee_kid: bytes
+    room_id: str
+    topic: str
+    issued_hlc_ms: int
+    initial_alpha_contribution: float
+    remaining_factor: float = 1.0  # 1.0 = no decay yet
+
+
+# Decay rate per day (matches reputation kernel's smooth-slash λ).
+_DECAY_LAMBDA_PER_DAY = 0.02
+_MS_PER_DAY = 1000 * 60 * 60 * 24
+
+
+class TAL:
+    """Rooms + vouch log with lazy decay, layered on a ReputationKernel."""
+
+    def __init__(self, reputation_kernel: ReputationKernel) -> None:
+        self._rep = reputation_kernel
+        self._rooms: dict[str, Room] = {}
+        self._vouch_log: list[_VouchRecord] = []
+
+    # ---- Rooms ----------------------------------------------------------
+
+    def create_room(self, room_id: str, min_reputation: float, creator_kid: bytes) -> Room:
+        if room_id in self._rooms:
+            raise TALError(f"room {room_id!r} already exists")
+        room = Room(
+            room_id=room_id,
+            min_reputation=min_reputation,
+            members={bytes(creator_kid)},
+            creator_kid=bytes(creator_kid),
+        )
+        self._rooms[room_id] = room
+        return room
+
+    def get_room(self, room_id: str) -> Room | None:
+        return self._rooms.get(room_id)
+
+    def join_room(self, agent_kid: bytes, room_id: str) -> None:
+        room = self._rooms.get(room_id)
+        if room is None:
+            raise TALError(f"room {room_id!r} does not exist")
+        if room.min_reputation > 0.0:
+            best = self._max_reputation(agent_kid)
+            if best < room.min_reputation:
+                raise TALError("reputation below room minimum")
+        room.members.add(bytes(agent_kid))
+
+    def _max_reputation(self, agent_kid: bytes) -> float:
+        """Best score across every (agent, topic) the kernel has seen."""
+        kid = bytes(agent_kid)
+        best = 0.0
+        for (a, topic), _p in self._rep._posteriors.items():
+            if a == kid:
+                score = self._rep.snapshot(kid, topic).score
+                if score > best:
+                    best = score
+        return best
+
+    # ---- Vouches --------------------------------------------------------
+
+    def vouch(
+        self,
+        voucher_kid: bytes,
+        vouchee_kid: bytes,
+        room_id: str,
+        topic: str,
+        *,
+        now_hlc_ms: int = 0,
+    ) -> None:
+        """Record a vouch and delegate the α contribution to the kernel.
+
+        The reputation kernel applies the 5%-of-α-above-prior cap; the
+        vouch log here is the bookkeeping needed for ``decay_vouches``.
+        """
+        if room_id not in self._rooms:
+            raise TALError(f"room {room_id!r} does not exist")
+        voucher_kid = bytes(voucher_kid)
+        vouchee_kid = bytes(vouchee_kid)
+        before = self._rep._get(vouchee_kid, topic).alpha
+        self._rep.vouch(voucher_kid, vouchee_kid, topic, strength=1.0)
+        after = self._rep._get(vouchee_kid, topic).alpha
+        contribution = max(0.0, after - before)
+        self._vouch_log.append(
+            _VouchRecord(
+                voucher_kid=voucher_kid,
+                vouchee_kid=vouchee_kid,
+                room_id=room_id,
+                topic=topic,
+                issued_hlc_ms=int(now_hlc_ms),
+                initial_alpha_contribution=contribution,
+                remaining_factor=1.0,
+            )
+        )
+
+    def decay_vouches(self, now_hlc_ms: int) -> None:
+        """Exponentially decay vouches older than 24h.
+
+        For each vouch in the log: compute days_elapsed since issue,
+        target_factor = max(0, 1 - λ · days_elapsed). Reduce the
+        vouchee's α by the difference between the previously-applied
+        factor and the new one. Bounded below at 0 — never refunds.
+        """
+        for v in self._vouch_log:
+            elapsed_ms = max(0, now_hlc_ms - v.issued_hlc_ms)
+            elapsed_days = elapsed_ms / _MS_PER_DAY
+            if elapsed_days < 1.0:
+                continue
+            new_factor = max(0.0, 1.0 - _DECAY_LAMBDA_PER_DAY * elapsed_days)
+            if new_factor >= v.remaining_factor:
+                continue  # nothing to remove
+            delta = (v.remaining_factor - new_factor) * v.initial_alpha_contribution
+            if delta <= 0:
+                continue
+            p = self._rep._get(v.vouchee_kid, v.topic)
+            p.alpha = max(1.0, p.alpha - delta)
+            v.remaining_factor = new_factor
+
+    # ---- Queries --------------------------------------------------------
+
+    def trust_query(self, kid: bytes, room_id: str) -> TrustStatus:
+        kid = bytes(kid)
+        room = self._rooms.get(room_id)
+        in_room = bool(room and kid in room.members)
+        rep = self._max_reputation(kid)
+        vouch_count = sum(
+            1 for v in self._vouch_log if v.vouchee_kid == kid and v.room_id == room_id
+        )
+        return TrustStatus(
+            in_room=in_room,
+            reputation_snapshot=rep,
+            vouch_count=vouch_count,
+        )

hypermind/tasks.py

@@ -0,0 +1,334 @@
+"""Task delegation primitives — spec §4.4.
+
+v0.10.1 (T1-04 / T1-05) adds a :class:`TaskGateway` Protocol so
+:func:`submit_task` can dispatch in-process *or* over a network
+transport (MCP / libp2p). The default :class:`InProcessGateway`
+preserves the v0.x asyncio-Future semantics; :class:`MCPGateway`
+dispatches over an :class:`MCPClient` and awaits a remote
+``submit_task`` reply.
+
+Cancellation, timeout, and idempotent retry are gateway-level
+concerns:
+
+- :meth:`TaskHandle.cancel` flips the handle's status to ``cancelled``
+  and asks its gateway (if any) to propagate a TASK_CANCEL signal.
+- :meth:`TaskHandle.result` uses :func:`asyncio.wait_for` for
+  timeouts; on timeout the handle is implicitly cancelled.
+- :class:`MCPGateway` keys an in-memory cache by ``request_kid`` so a
+  duplicate :func:`submit_task` (same descriptor) returns the cached
+  :class:`TaskHandle` rather than dispatching twice.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import secrets
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal, Protocol
+
+import cbor2
+
+if TYPE_CHECKING:  # pragma: no cover
+    from hypermind.crypto.signing import Keypair
+    from hypermind.mcp.client import MCPClient
+
+
+@dataclass
+class TaskDescriptor:
+    """The signed payload describing a unit of remote work.
+
+    Used by :class:`TaskGateway` implementations to dispatch a task
+    over a transport. Independent of any specific wire format —
+    gateways serialise the descriptor as they see fit.
+    """
+
+    task_id: str
+    submitter_kid: bytes
+    assignee_kid: bytes
+    topic: str
+    arguments: dict[str, Any] = field(default_factory=dict)
+    timeout_s: float = 30.0
+
+    def to_canonical_cbor(self) -> bytes:
+        """RFC 8949 §4.2 deterministic CBOR for hashing / idempotency."""
+        return cbor2.dumps(
+            {
+                "task_id": self.task_id,
+                "submitter_kid": self.submitter_kid,
+                "assignee_kid": self.assignee_kid,
+                "topic": self.topic,
+                "arguments": self.arguments,
+                "timeout_s": self.timeout_s,
+            },
+            canonical=True,
+        )
+
+    @property
+    def request_kid(self) -> bytes:
+        """SHA-256 of the canonical encoding — the idempotency key."""
+        return hashlib.sha256(self.to_canonical_cbor()).digest()
+
+
+@dataclass
+class TaskHandle:
+    """Awaitable handle for a submitted task (spec §4.4).
+
+    Returned by :func:`submit_task`; callers ``await handle.result()`` to
+    block until the assignee completes the work or the timeout fires.
+    Cancellation propagates to the gateway so remote tasks receive a
+    TASK_CANCEL signal when possible.
+
+    Examples:
+        >>> handle = await submit_task(
+        ...     submitter_kid=alice.keypair.kid,
+        ...     assignee_kid=bob.keypair.kid,
+        ...     topic="ai-safety/eval",
+        ...     arguments={"claim_id": kid.hex()},
+        ...     timeout_s=30.0,
+        ... )
+        >>> result = await handle.result(timeout=30.0)
+    """
+
+    task_id: str  # hex uuid
+    submitter_kid: bytes
+    assignee_kid: bytes
+    topic: str
+    _result_future: asyncio.Future = field(
+        default_factory=lambda: asyncio.get_event_loop().create_future(),
+        repr=False,
+    )
+    _status: Literal["pending", "running", "complete", "failed"] = "pending"
+    _gateway: TaskGateway | None = field(default=None, repr=False)
+    _request_kid: bytes = field(default=b"", repr=False)
+
+    @property
+    def status(self) -> str:
+        return self._status
+
+    @property
+    def request_kid(self) -> bytes:
+        return self._request_kid
+
+    async def result(self, timeout: float = 30.0) -> Any:
+        """Wait for task completion.
+
+        Returns the result payload or raises TaskTimeoutError/TaskFailedError.
+        On timeout the handle transitions to ``cancelled`` and the
+        gateway is asked to propagate a TASK_CANCEL signal (T1-05).
+        """
+        if self._status == "failed":
+            raise TaskFailedError(f"Task {self.task_id} failed or was cancelled")
+        try:
+            return await asyncio.wait_for(asyncio.shield(self._result_future), timeout=timeout)
+        except TimeoutError as e:
+            await self.cancel()
+            raise TaskTimeoutError(f"Task {self.task_id} timed out after {timeout}s") from e
+        except asyncio.CancelledError as e:
+            raise TaskFailedError(f"Task {self.task_id} was cancelled") from e
+
+    def _resolve(self, value: Any) -> None:
+        """Resolve the future with a result value. Called by the task framework."""
+        self._status = "complete"
+        if not self._result_future.done():
+            self._result_future.set_result(value)
+
+    def _fail(self, exc: BaseException | None = None) -> None:
+        """Mark the task as failed. Called by the task framework."""
+        self._status = "failed"
+        if not self._result_future.done():
+            if exc is not None:
+                self._result_future.set_exception(exc)
+            else:
+                self._result_future.cancel()
+
+    async def cancel(self) -> None:
+        """Cancel this task handle.
+
+        Propagates a TASK_CANCEL signal via the bound gateway when one
+        is set (T1-05). Local-only handles flip status without any
+        network traffic.
+        """
+        if self._status in ("complete", "failed"):
+            return
+        # Backwards-compat: cancel transitions to "failed" (v0.x contract).
+        self._status = "failed"
+        if not self._result_future.done():
+            self._result_future.cancel()
+        if self._gateway is not None:
+            try:
+                await self._gateway.cancel(self)
+            except Exception:
+                pass
+
+
+class TaskTimeoutError(Exception):
+    """Raised when a task result is not received within the timeout."""
+
+
+class TaskFailedError(Exception):
+    """Raised when a task fails or is cancelled."""
+
+
+# ---------------------------------------------------------------------------
+# Gateway Protocol + implementations (T1-04)
+# ---------------------------------------------------------------------------
+
+
+class TaskGateway(Protocol):
+    """Dispatch interface for :func:`submit_task`.
+
+    Implementations turn a :class:`TaskDescriptor` into a
+    :class:`TaskHandle` whose future is fulfilled when the task
+    completes (locally or remotely). Cancellation is propagated
+    through :meth:`cancel`.
+    """
+
+    async def dispatch(self, descriptor: TaskDescriptor) -> TaskHandle: ...
+
+    async def cancel(self, handle: TaskHandle) -> None: ...
+
+
+class InProcessGateway:
+    """Default gateway — returns a bare :class:`TaskHandle`.
+
+    The handle is fulfilled by whoever owns the in-process bus / agent
+    plumbing (this module does not auto-resolve; v0.x callers were
+    already wiring resolution themselves).
+    """
+
+    async def dispatch(self, descriptor: TaskDescriptor) -> TaskHandle:
+        handle = TaskHandle(
+            task_id=descriptor.task_id,
+            submitter_kid=descriptor.submitter_kid,
+            assignee_kid=descriptor.assignee_kid,
+            topic=descriptor.topic,
+            _gateway=self,
+            _request_kid=descriptor.request_kid,
+        )
+        return handle
+
+    async def cancel(self, handle: TaskHandle) -> None:
+        # Local handle — nothing to propagate beyond the future cancellation
+        # already performed inside TaskHandle.cancel().
+        return None
+
+
+class MCPGateway:
+    """Dispatch :func:`submit_task` over an :class:`MCPClient`.
+
+    The remote server MUST expose two tools:
+
+    - ``submit_task`` — accepts the serialised descriptor, returns a
+      ``{"task_id": ..., "result": ...}`` envelope on completion.
+    - ``cancel_task`` — accepts ``{"task_id": ...}``.
+
+    Idempotency: if the same descriptor (== same ``request_kid``) is
+    dispatched twice, the second call returns the cached
+    :class:`TaskHandle` from the first dispatch (T1-05).
+    """
+
+    def __init__(
+        self,
+        client: MCPClient,
+        *,
+        signing_keypair: Keypair,
+        cap_token_root: bytes,
+    ) -> None:
+        self._client = client
+        self._keypair = signing_keypair
+        self._cap_token_root = cap_token_root
+        self._pending: dict[bytes, TaskHandle] = {}
+        self._tasks: dict[bytes, asyncio.Task] = {}
+
+    async def dispatch(self, descriptor: TaskDescriptor) -> TaskHandle:
+        request_kid = descriptor.request_kid
+        # Idempotent retry: same descriptor → same handle.
+        if request_kid in self._pending:
+            return self._pending[request_kid]
+
+        handle = TaskHandle(
+            task_id=descriptor.task_id,
+            submitter_kid=descriptor.submitter_kid,
+            assignee_kid=descriptor.assignee_kid,
+            topic=descriptor.topic,
+            _gateway=self,
+            _request_kid=request_kid,
+        )
+        self._pending[request_kid] = handle
+
+        async def _run() -> None:
+            try:
+                envelope = await self._client.call_tool(
+                    "submit_task",
+                    {
+                        "task_id": descriptor.task_id,
+                        "submitter_kid": descriptor.submitter_kid.hex(),
+                        "assignee_kid": descriptor.assignee_kid.hex(),
+                        "topic": descriptor.topic,
+                        "arguments": descriptor.arguments,
+                    },
+                    signing_keypair=self._keypair,
+                    cap_token_root=self._cap_token_root,
+                )
+                content = envelope.get("content") if isinstance(envelope, dict) else envelope
+                handle._resolve(content)
+            except asyncio.CancelledError:
+                handle._fail(TaskFailedError("task cancelled"))
+                raise
+            except Exception as e:
+                handle._fail(e)
+
+        self._tasks[request_kid] = asyncio.create_task(_run())
+        return handle
+
+    async def cancel(self, handle: TaskHandle) -> None:
+        kid = handle.request_kid
+        task = self._tasks.pop(kid, None)
+        if task is not None and not task.done():
+            task.cancel()
+        # Best-effort remote cancel — ignore errors, the remote side
+        # may have already completed or never seen the task.
+        try:
+            await self._client.call_tool(
+                "cancel_task",
+                {"task_id": handle.task_id},
+                signing_keypair=self._keypair,
+                cap_token_root=self._cap_token_root,
+            )
+        except Exception:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# submit_task entry point
+# ---------------------------------------------------------------------------
+
+
+async def submit_task(
+    *,
+    submitter_kid: bytes,
+    assignee_kid: bytes,
+    topic: str,
+    arguments: dict[str, Any] | None = None,
+    timeout_s: float = 30.0,
+    gateway: TaskGateway | None = None,
+    task_id: str | None = None,
+) -> TaskHandle:
+    """Submit a task to a :class:`TaskGateway`.
+
+    Defaults to :class:`InProcessGateway` to preserve v0.x semantics
+    (callers that already wire resolution into the in-process bus
+    continue to work unchanged). Pass a :class:`MCPGateway` to
+    dispatch over a network transport (T1-04).
+    """
+    descriptor = TaskDescriptor(
+        task_id=task_id or secrets.token_hex(8),
+        submitter_kid=submitter_kid,
+        assignee_kid=assignee_kid,
+        topic=topic,
+        arguments=arguments or {},
+        timeout_s=timeout_s,
+    )
+    gw = gateway if gateway is not None else InProcessGateway()
+    return await gw.dispatch(descriptor)