glowcap 0.1.1__py3-none-any.whl

glowcap/__init__.py

@@ -0,0 +1,189 @@
+"""Idiomatic Python API for glowcap, an OCapN/CapTP Host driven by the
+symbol-disjoint Host and driver archives (ADR-0024).
+
+This is the core package: it rides ``libglowcap_ocapn`` (the shared value and
+locator vocabulary), ``libglowcap_host`` (the byte-fed multi-session Host),
+and ``libglowcap_driver`` (the stepping driver that adopts that Host). It does
+not choose or load a concrete transport. The raw ``ctypes``
+FFI lives in the internal ``_ffi_*`` modules. This package is the public
+surface over it. What you hold is a :class:`Session`: compose a :class:`Runtime`,
+dial with its ``connect`` method, accept through a transport module's
+``listen``, and speak plain Python values:
+``int``/``float``/``bool``/``bytes``/``str``/``list``, plus :class:`Symbol`,
+:class:`Keyword`, :class:`Set`, :class:`Tagged`, :class:`Struct`, and the capability
+:class:`Ref`:
+
+    async with Runtime.open(provider=tcp.provider()) as runtime:
+        async with await runtime.connect(tcp.locator("127.0.0.1", 9099)) as session:
+            greeter = await session.fetch("greeter")
+            reply = await session.send(greeter, "greet", ["world"])
+
+The host owns routing, three-party redemption, and gift origination. The
+binding moves bytes and honors the host's action queue. A :class:`Host` is the
+CapTP Host those sessions share, one identity and one handoff router, read as
+``server.host`` or transferred into :class:`Runtime`.
+
+The C ABI ships as a set of composable, symbol-disjoint archives (ADR-0022),
+and this package mirrors that à la carte: the core here, plus one submodule
+per transport. Each transport submodule loads only its own archive, so
+importing one transport never loads another. Compose what you need:
+
+    from glowcap import Runtime, tcp
+    from glowcap.tcp import TcpNetlayer        # libglowcap_net_transport_tcp
+    from glowcap.inproc import InprocNetlayer  # libglowcap_net_transport_inproc
+    from glowcap.iroh import listen            # libglowcap_net_transport_iroh
+
+The async :class:`Runtime` / :class:`Session` surface here is transport-neutral.
+Callers explicitly compose a transport's ``provider(config)``
+or ``connector(...)`` with :class:`Runtime`. No locator-shape dispatch or byte
+fallback occurs in this module. A ``tcp``, ``keyed-tcp``, ``noise-tcp``,
+``iroh``, or routed relay connection runs on the driver archive: one stepping
+loop owns the provider, pumping, and session release, parked on the asyncio
+reactor. A plain TCP application needs this core plus :mod:`glowcap.tcp`, which also
+holds the blocking ``glowcap_tcp_*`` frame shuttle. The socket-free in-process
+transport lives in :mod:`glowcap.inproc`, the encrypted-QUIC transport in
+:mod:`glowcap.iroh`, and the WebRTC dial in :mod:`glowcap.webrtc`. The core never imports one of those modules based on locator shape.
+
+The implementation is split by responsibility across ``_``-private submodules
+(``_errors``, ``_value``, ``_abi_value``, ``_context``, ``_locator``,
+``_trampoline``, ``_host``, ``_action``, ``_promise``, ``_gc``, ``_dial``,
+``_loop``, ``_pump``, ``_session``) alongside the per-archive ``_ffi_*``
+loaders. This module is the barrel that re-exports the public surface. Import
+every name from :mod:`glowcap`: the submodule layout is internal.
+"""
+
+from __future__ import annotations
+
+from ._carrier_failure import CarrierFailure, CarrierPhase
+from ._constants import (
+    FEATURE_BASELINE,
+    FEATURE_FULL,
+    FEATURE_HANDOFF,
+    FEATURE_MINIMUM,
+    FEATURE_MULTI_LOCATION,
+    FEATURE_PIPELINING,
+    FEATURE_STURDYREF,
+    FEATURE_UNTAG,
+    FEATURE_WIRE_DELTA,
+    HANDSHAKE_TIMEOUT_MS,
+    HINT_ALT_LOCATORS,
+    HINT_DIRECT_ADDRESSES,
+    HINT_VIA,
+    TRANSPORT_ID,
+    TRANSPORT_INPROC,
+    TRANSPORT_IROH,
+    TRANSPORT_KEYED_RELAY,
+    TRANSPORT_KEYED_TCP,
+    TRANSPORT_NOISE_RELAY,
+    TRANSPORT_NOISE_TCP,
+    TRANSPORT_ONION,
+    TRANSPORT_TCP,
+    TRANSPORT_WEBRTC,
+    DurableProvenance,
+)
+from ._context import Context
+from ._dial import Runtime
+
+# Re-export the public surface from the per-responsibility submodules, in
+# dependency order (errors and values first, then the Host and the application
+# surface). A consumer imports every name from :mod:`glowcap`.
+from ._errors import AbortDetail, FetchFailed, GlowcapError, VowBroken, abi_version, last_error
+from ._failure import FailureEvent, FailureLayer, FailureScope, take_runtime_failures
+from ._host import Host
+from ._lifecycle import PendingWork
+from ._locator import (
+    Locator,
+    SturdyRef,
+    designator_host_port,
+    encode_peer_locator,
+    format_locator_uri,
+    format_peer_uri,
+    format_sturdyref,
+    parse_locator,
+    parse_sturdyref,
+)
+from ._promise import RemotePromise
+from ._session import PartnerIdentity, SendRedeemingResult, Session, SessionProfile
+from ._trace import annotate_session, enable_trace
+from ._trampoline import Caretaker
+from ._transport import Connector, Provider
+from ._value import Argument, ErrorValue, Forward, Keyword, Ref, Set, Struct, Symbol, Tagged
+
+__all__ = [
+    # Version and diagnostics
+    "abi_version",
+    "last_error",
+    "take_runtime_failures",
+    "AbortDetail",
+    "CarrierFailure",
+    "CarrierPhase",
+    # Exceptions
+    "GlowcapError",
+    "VowBroken",
+    "FetchFailed",
+    # Argument vocabulary
+    "Ref",
+    "Symbol",
+    "Keyword",
+    "ErrorValue",
+    "Set",
+    "Tagged",
+    "Struct",
+    "Forward",
+    "Argument",
+    # Allocation scope
+    "Context",
+    "FailureEvent",
+    "FailureLayer",
+    "FailureScope",
+    # Application surface
+    "Session",
+    "SessionProfile",
+    "SendRedeemingResult",
+    "DurableProvenance",
+    "PartnerIdentity",
+    "RemotePromise",
+    "Host",
+    "PendingWork",
+    "Caretaker",
+    "Runtime",
+    "Provider",
+    "Connector",
+    "annotate_session",
+    "enable_trace",
+    "HANDSHAKE_TIMEOUT_MS",
+    "FEATURE_MINIMUM",
+    "FEATURE_BASELINE",
+    "FEATURE_PIPELINING",
+    "FEATURE_HANDOFF",
+    "FEATURE_WIRE_DELTA",
+    "FEATURE_STURDYREF",
+    "FEATURE_UNTAG",
+    "FEATURE_MULTI_LOCATION",
+    "FEATURE_FULL",
+    # Locator grammar
+    "Locator",
+    "SturdyRef",
+    "parse_locator",
+    "parse_sturdyref",
+    "format_locator_uri",
+    "format_peer_uri",
+    "format_sturdyref",
+    "designator_host_port",
+    "encode_peer_locator",
+    # Transport symbols
+    "TRANSPORT_TCP",
+    "TRANSPORT_ID",
+    "TRANSPORT_KEYED_TCP",
+    "TRANSPORT_ONION",
+    "TRANSPORT_NOISE_TCP",
+    "TRANSPORT_NOISE_RELAY",
+    "TRANSPORT_INPROC",
+    "TRANSPORT_IROH",
+    "TRANSPORT_KEYED_RELAY",
+    "TRANSPORT_WEBRTC",
+    # Locator hint keys
+    "HINT_ALT_LOCATORS",
+    "HINT_DIRECT_ADDRESSES",
+    "HINT_VIA",
+]

glowcap/_abi_value.py

@@ -0,0 +1,308 @@
+"""Internal: the ctypes ABI value and option projection.
+
+Marshals the value vocabulary to and from the C ABI ``_Argument`` / ``_Reference``
+structs: ``_arg_to_c`` / ``_args_to_c`` / ``_ref_to_c`` on the way out
+(retaining each borrowed byte owner on a caller-supplied ``keepalive`` list for
+the duration of the synchronous C call), ``_arg_from_c`` / ``_ref_from_c`` on
+the way back.
+This module does not encode or decode CapTP frames. Zig owns both wire codecs
+and every protocol decision. Re-exported value types come from :mod:`glowcap`.
+"""
+
+from __future__ import annotations
+
+import array
+import asyncio
+import ctypes
+from collections.abc import Callable
+
+from . import _constants as _abi
+from ._errors import GlowcapError
+from ._ffi_ocapn import _Argument, _borrowed_byte_ptr, _Reference
+from ._value import Argument, ErrorValue, Keyword, Ref, Set, Struct, Symbol, Tagged, _ref_from_id
+
+_ERR_INVALID_ARGUMENT = _abi.ERR_INVALID_ARGUMENT
+_ERR_INTERNAL = _abi.ERR_INTERNAL
+_ERR_UNSUPPORTED_VALUE = _abi.ERR_UNSUPPORTED_VALUE
+
+_ARG_INTEGER, _ARG_FLOAT64, _ARG_BOOLEAN, _ARG_BYTES = (
+    _abi.ARG_INTEGER,
+    _abi.ARG_FLOAT64,
+    _abi.ARG_BOOLEAN,
+    _abi.ARG_BYTES,
+)
+_ARG_STRING, _ARG_SYMBOL, _ARG_VOID, _ARG_REFERENCE, _ARG_LIST = (
+    _abi.ARG_STRING,
+    _abi.ARG_SYMBOL,
+    _abi.ARG_VOID,
+    _abi.ARG_REFERENCE,
+    _abi.ARG_LIST,
+)
+_ARG_SET, _ARG_TAGGED, _ARG_KEYWORD = _abi.ARG_SET, _abi.ARG_TAGGED, _abi.ARG_KEYWORD
+_ARG_BIG_INTEGER = _abi.ARG_BIG_INTEGER
+_ARG_INTEGERS = _abi.ARG_INTEGERS
+_ARG_STRUCT = _abi.ARG_STRUCT
+_ARG_ERROR = _abi.ARG_ERROR
+_FEATURE_FULL = _abi.FEATURE_FULL
+
+
+def _codec_name(codec: int, source: str | None = None) -> str:
+    if codec == _abi.CODEC_SYRUP:
+        return "syrup"
+    if codec == _abi.CODEC_CAPNP:
+        return "capnp"
+    if source is not None:
+        raise RuntimeError(f"glowcap ABI returned unknown {source} codec {codec!r}")
+    raise RuntimeError(f"glowcap ABI generated unknown default codec {codec!r}")
+
+
+def _captp_version_name(version: int, source: str | None = None) -> str:
+    if version == _abi.CAPTP_V1_0:
+        return "v1_0"
+    if version == _abi.CAPTP_NEXT:
+        return "next"
+    if source is not None:
+        raise RuntimeError(f"glowcap ABI returned unknown {source} CapTP version {version!r}")
+    raise RuntimeError(f"glowcap ABI generated unknown default CapTP version {version!r}")
+
+
+def _feature_name(features: int):
+    if features == _abi.FEATURE_FULL:
+        return "full"
+    if features == _abi.FEATURE_BASELINE:
+        return "baseline"
+    if features == _abi.FEATURE_MINIMUM:
+        return "minimum"
+    return features
+
+
+_DEFAULT_CODEC = _codec_name(_abi.DEFAULT_CODEC)
+_DEFAULT_CAPTP_VERSION = _captp_version_name(_abi.DEFAULT_CAPTP_VERSION)
+_DEFAULT_FEATURES = _feature_name(_abi.DEFAULT_FEATURES)
+_INTEROP_CODEC = _codec_name(_abi.INTEROP_CODEC)
+_INTEROP_CAPTP_VERSION = _captp_version_name(_abi.INTEROP_CAPTP_VERSION)
+_OWN_CODEC = _codec_name(_abi.OWN_CODEC)
+_OWN_CAPTP_VERSION = _captp_version_name(_abi.OWN_CAPTP_VERSION)
+
+
+def _captp_version_id(version: str) -> int:
+    """The ``GLOWCAP_CAPTP_*`` id for a CapTP profile name (ADR-0001).
+    ``v1_0`` is the interop floor a Goblins vat speaks. ``next`` is the
+    glowcap-to-glowcap track ``Offer.glowcap`` prefers with Cap'n Proto."""
+    if version == "v1_0":
+        return _abi.CAPTP_V1_0
+    if version == "next":
+        return _abi.CAPTP_NEXT
+    raise ValueError(f'captp_version must be "v1_0" or "next", got {version!r}')
+
+
+def _codec_id(codec: str) -> int:
+    """The ``GLOWCAP_CODEC_*`` id for a codec name, the selector
+    ``glowcap_host_new`` and the blocking transport connections take."""
+    if codec == "syrup":
+        return _abi.CODEC_SYRUP
+    if codec == "capnp":
+        return _abi.CODEC_CAPNP
+    raise ValueError(f"unknown OCapN codec {codec!r}")
+
+
+def _feature_mask(features) -> int:
+    """The ``GLOWCAP_FEATURE_*`` bitmask for a Host feature offer."""
+    if features == "full":
+        return _abi.FEATURE_FULL
+    if features == "baseline":
+        return _abi.FEATURE_BASELINE
+    if features == "minimum":
+        return _abi.FEATURE_MINIMUM
+    if isinstance(features, int) and not isinstance(features, bool):
+        if features < 0 or features & ~_FEATURE_FULL:
+            raise ValueError(f"unknown OCapN feature mask {features!r}")
+        return features
+    mask = 0
+    for feature in features:
+        if feature == "pipelining":
+            mask |= _abi.FEATURE_PIPELINING
+        elif feature == "handoff":
+            mask |= _abi.FEATURE_HANDOFF
+        elif feature == "wire_delta":
+            mask |= _abi.FEATURE_WIRE_DELTA
+        elif feature == "sturdyref":
+            mask |= _abi.FEATURE_STURDYREF
+        elif feature == "untag":
+            mask |= _abi.FEATURE_UNTAG
+        elif feature == "multi_location":
+            mask |= _abi.FEATURE_MULTI_LOCATION
+        else:
+            raise ValueError(f"unknown OCapN feature {feature!r}")
+    return mask
+
+
+def _ref_to_c(ref: Ref) -> _Reference:
+    return _Reference(ref._live().id)
+
+
+# The capability a promise among send arguments travels as (ADR-0068). Only
+# the far send and tell paths supply one; everywhere else a promise is an
+# unsupported argument value.
+_PromiseLowering = Callable[[asyncio.Future], Ref]
+
+
+def _arg_to_c(value: Argument, keepalive: list, lower: _PromiseLowering | None = None) -> _Argument:
+    a = _Argument()
+    if isinstance(value, array.array) and value.typecode == "q":
+        # Export the buffer before reading its address: retaining the array
+        # alone permits another thread to resize it while CDLL releases the
+        # GIL. The export pins its storage for the call. Empty is NULL and 0.
+        a.kind = _ARG_INTEGERS
+        words = memoryview(value)
+        if words.nbytes:
+            keepalive.append(words)
+            a.bytes = value.buffer_info()[0]
+            a.bytes_len = words.nbytes
+    elif isinstance(value, bool):  # before int; bool is an int subclass
+        a.kind, a.boolean = _ARG_BOOLEAN, 1 if value else 0
+    elif isinstance(value, int):
+        # ctypes silently wraps an out-of-range int mod 2**64; OCapN integers are
+        # bignums, so refuse anything the C ABI int64 cannot carry rather than
+        # send a corrupted value.
+        if not (-(2**63) <= value < 2**63):
+            # Outside the C ABI int64: ARG_BIG_INTEGER carries the canonical
+            # decimal digits in bytes/bytes_len and the sign in boolean (ADR-0005).
+            _set_bytes(a, _ARG_BIG_INTEGER, str(abs(value)).encode(), keepalive)
+            a.boolean = 1 if value < 0 else 0
+        else:
+            a.kind, a.integer = _ARG_INTEGER, value
+    elif isinstance(value, float):
+        a.kind, a.float64 = _ARG_FLOAT64, value
+    elif isinstance(value, Symbol):  # before str
+        _set_bytes(a, _ARG_SYMBOL, value.encode(), keepalive)
+    elif isinstance(value, Keyword):  # before str
+        _set_bytes(a, _ARG_KEYWORD, value.encode(), keepalive)
+    elif isinstance(value, ErrorValue):
+        _set_bytes(a, _ARG_ERROR, value.message.encode(), keepalive)
+    elif isinstance(value, str):
+        _set_bytes(a, _ARG_STRING, value.encode(), keepalive)
+    elif isinstance(value, (bytes, bytearray)):
+        _set_bytes(a, _ARG_BYTES, bytes(value), keepalive)
+    elif value is None:
+        a.kind = _ARG_VOID
+    elif isinstance(value, Ref):
+        a.kind, a.reference = _ARG_REFERENCE, _ref_to_c(value)
+    elif isinstance(value, asyncio.Future):
+        if lower is None:
+            raise GlowcapError(_ERR_UNSUPPORTED_VALUE, "a promise is passable only as a send or tell argument")
+        a.kind, a.reference = _ARG_REFERENCE, _ref_to_c(lower(value))
+    elif isinstance(value, Tagged):
+        _set_bytes(a, _ARG_TAGGED, value.tag.encode(), keepalive)
+        a.items, a.items_len = _args_to_c(list(value.value), keepalive, lower)
+    elif isinstance(value, Struct):
+        a.kind = _ARG_STRUCT
+        a.items, a.items_len = _struct_entries_to_c(value.entries, keepalive, lower)
+    elif isinstance(value, Set):  # before list
+        a.kind = _ARG_SET
+        a.items, a.items_len = _args_to_c(list(value), keepalive, lower)
+    elif isinstance(value, list):
+        a.kind = _ARG_LIST
+        a.items, a.items_len = _args_to_c(value, keepalive, lower)
+    else:
+        raise GlowcapError(_ERR_UNSUPPORTED_VALUE, "unsupported argument value")
+    return a
+
+
+def _set_bytes(a: _Argument, kind: int, data: bytes, keepalive: list) -> None:
+    owner, ptr = _borrowed_byte_ptr(data)
+    keepalive.append(owner)
+    a.kind = kind
+    a.bytes = ptr
+    a.bytes_len = len(data)
+
+
+def _args_to_c(args: list, keepalive: list, lower: _PromiseLowering | None = None):
+    n = len(args)
+    if n == 0:
+        return (None, 0)
+    arr = (_Argument * n)()
+    for i, value in enumerate(args):
+        arr[i] = _arg_to_c(value, keepalive, lower)
+    keepalive.append(arr)
+    return (arr, n)
+
+
+def _struct_entries_to_c(entries: list[tuple[str, Argument]], keepalive: list, lower: _PromiseLowering | None = None):
+    n = len(entries) * 2
+    if n == 0:
+        return (None, 0)
+    arr = (_Argument * n)()
+    for i, (key, value) in enumerate(entries):
+        if not isinstance(key, str) or isinstance(key, (Symbol, Keyword)):
+            raise GlowcapError(_ERR_UNSUPPORTED_VALUE, "Struct entries must be String/value pairs")
+        key_arg = _Argument()
+        _set_bytes(key_arg, _ARG_STRING, key.encode(), keepalive)
+        arr[i * 2] = key_arg
+        arr[i * 2 + 1] = _arg_to_c(value, keepalive, lower)
+    keepalive.append(arr)
+    return (arr, n)
+
+
+def _ref_from_c(r: _Reference) -> Ref:
+    return _ref_from_id(r.id)
+
+
+def _bytes_from_c(a: _Argument) -> bytes:
+    if not a.bytes or a.bytes_len == 0:
+        return b""
+    return ctypes.string_at(a.bytes, a.bytes_len)
+
+
+def _arg_from_c(a: _Argument) -> Argument:
+    if a.kind == _ARG_INTEGER:
+        return a.integer
+    if a.kind == _ARG_FLOAT64:
+        return a.float64
+    if a.kind == _ARG_BOOLEAN:
+        return a.boolean != 0
+    if a.kind == _ARG_BYTES:
+        return _bytes_from_c(a)
+    # Syrup strings/symbols are unchecked partner bytes; decode leniently so a
+    # untrusted non-UTF-8 payload surfaces as a value (matching Rust's
+    # from_utf8_lossy and Deno's non-fatal TextDecoder) instead of crashing the
+    # poll with UnicodeDecodeError.
+    if a.kind == _ARG_STRING:
+        return _bytes_from_c(a).decode(errors="replace")
+    if a.kind == _ARG_SYMBOL:
+        return Symbol(_bytes_from_c(a).decode(errors="replace"))
+    if a.kind == _ARG_ERROR:
+        return ErrorValue(_bytes_from_c(a).decode(errors="replace"))
+    if a.kind == _ARG_REFERENCE:
+        return _ref_from_c(a.reference)
+    if a.kind == _ARG_LIST:
+        return [_arg_from_c(a.items[i]) for i in range(a.items_len)]
+    if a.kind == _ARG_SET:
+        return Set(_arg_from_c(a.items[i]) for i in range(a.items_len))
+    if a.kind == _ARG_TAGGED:
+        return Tagged(_bytes_from_c(a).decode(errors="replace"), [_arg_from_c(a.items[i]) for i in range(a.items_len)])
+    if a.kind == _ARG_KEYWORD:
+        return Keyword(_bytes_from_c(a).decode(errors="replace"))
+    if a.kind == _ARG_VOID:
+        return None
+    if a.kind == _ARG_BIG_INTEGER:
+        # Canonical decimal digits + sign flag back to a Python int (ADR-0005).
+        magnitude = int(_bytes_from_c(a))
+        return -magnitude if a.boolean != 0 else magnitude
+    if a.kind == _ARG_INTEGERS:
+        # Copied out because the C memory is released after projection.
+        run = array.array("q")
+        run.frombytes(_bytes_from_c(a))
+        return run
+    if a.kind == _ARG_STRUCT:
+        if a.items_len % 2:
+            raise GlowcapError(_ERR_INTERNAL, "glowcap ABI returned an odd Struct item count")
+        entries: list[tuple[str, Argument]] = []
+        for i in range(0, a.items_len, 2):
+            key_arg = a.items[i]
+            if key_arg.kind != _ARG_STRING:
+                raise GlowcapError(_ERR_INTERNAL, "glowcap ABI returned a non-String Struct key")
+            key = _bytes_from_c(key_arg).decode(errors="replace")
+            entries.append((key, _arg_from_c(a.items[i + 1])))
+        return Struct(entries)
+    raise GlowcapError(_ERR_INTERNAL, f"glowcap ABI returned unknown argument kind {a.kind}")

glowcap/_action.py

@@ -0,0 +1,145 @@
+"""Internal: host-action execute: the embedder-contract switch the CapTP
+host drain runs.
+
+:class:`~glowcap._host.Host` owns park/kick/vows and the Session registry.
+Decode/types come from the generated ``_host_action_gen`` module
+(``zig build gen-binding-host-action``). This module owns the shared C drain
+(``glowcap_host_pump_drain``) with sync park-only hooks, then runs each parked
+arm (dial, flush, close, gift-id entropy, settle, fail) after the C loop
+returns: so async I/O never runs inside the C callback.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import secrets
+
+from . import _constants as _abi
+from ._errors import GlowcapError, _check_host, _vow_failure
+from ._ffi_host import _host, _HostPumpArmFn, _HostPumpHooks
+from ._ffi_ocapn import _byte_buf
+from ._host_action_gen import (
+    CancelDial,
+    Close,
+    Dial,
+    Fail,
+    Flush,
+    HostAction,
+    NeedGiftId,
+    Resume,
+    Settle,
+    decode,
+    dispatch,
+)
+
+_OK = _abi.OK
+
+
+def _answer_gift_id(draw, provide, failed) -> None:
+    """Complete entropy failure separately from FFI ticket refusal."""
+    try:
+        gift_id = draw()
+    except Exception:
+        failed()
+        return
+    provide(gift_id)
+
+
+def _park_actions(host) -> tuple[list[HostAction], bool]:
+    """Run ``glowcap_host_pump_drain`` with park-only arms. Return decoded
+    actions in queue order. Views are copied inside ``decode`` before the
+    next pop frees them."""
+    parked: list[HostAction] = []
+    callback_failure: BaseException | None = None
+
+    @_HostPumpArmFn
+    def park(_ctx, _host_ptr, action, out_progressed) -> int:
+        nonlocal callback_failure
+        try:
+            parked.append(decode(action.contents))
+        except BaseException as error:
+            callback_failure = error
+            return _abi.ERR_INTERNAL
+        if out_progressed:
+            out_progressed[0] = 1
+        return _OK
+
+    # Keep the callback + hooks alive for the duration of the C call via
+    # locals (do not stash on Host private fields).
+    hooks = _HostPumpHooks(None, park, park, park, park, park)
+    acted = ctypes.c_uint32(0)
+    yielded = ctypes.c_uint32(0)
+    rc = _host.glowcap_host_pump_drain(host.raw, ctypes.byref(hooks), ctypes.byref(acted), ctypes.byref(yielded))
+    if callback_failure is not None:
+        raise GlowcapError(
+            _abi.ERR_INTERNAL, f"glowcap ABI returned an invalid host action: {callback_failure}"
+        ) from callback_failure
+    _check_host(rc)
+    return parked, yielded.value != 0
+
+
+class _Handlers:
+    """The executor for popped host actions. Dumb by construction: every decision
+    was already made in the core. Each arm is pure I/O or marshalling. The
+    kind inventory lives in generated ``dispatch``, so a new kind fails
+    generate/check. One instance per Host: building this table per action
+    cost more than the action it dispatched."""
+
+    __slots__ = ("_host",)
+
+    def __init__(self, host) -> None:
+        self._host = host
+
+    async def dial(self, a: Dial) -> None:
+        # A popped DIAL is not owned by the FFI action queue. Hand
+        # it to the Host before returning so teardown can cancel and join it
+        # without serializing this drain behind network establishment.
+        from ._dial import run_dial_ticket
+
+        self._host.start_dial_task(
+            a.ticket, a.route_index, lambda: run_dial_ticket(self._host, a.ticket, a.route_index)
+        )
+
+    async def cancel_dial(self, a: CancelDial) -> None:
+        await self._host.cancel_dial_task(a.ticket, a.route_index)
+
+    async def flush(self, a: Flush) -> None:
+        # The session's writer owns the write, so this drain, and the serve
+        # loop running it, keeps reading while the partner is slow to. A write
+        # failure retires only that session, never this Host drain.
+        session = self._host.get_session(a.session_ptr)
+        if session is not None:
+            session.request_flush()
+
+    async def close(self, a: Close) -> None:
+        # The writer drains what the core queued ahead of this CLOSE, then
+        # retires the session and settles an explicit close.
+        session = self._host.get_session(a.session_ptr)
+        if session is not None:
+            session.close_after_flush(a.result)
+
+    async def need_gift_id(self, a: NeedGiftId) -> None:
+        def provide(gift_id: bytes) -> None:
+            buf, ptr = _byte_buf(gift_id)
+            _check_host(_host.glowcap_host_provide_gift_id(self._host.raw, a.ticket, ptr, 32))
+
+        _answer_gift_id(
+            lambda: secrets.token_bytes(32),
+            provide,
+            lambda: _check_host(_host.glowcap_host_gift_id_failed(self._host.raw, a.ticket)),
+        )
+
+    async def settle(self, a: Settle) -> None:
+        self._host.settle_vow(a.ticket, True, a.value)
+
+    async def fail(self, a: Fail) -> None:
+        self._host.settle_vow(a.ticket, False, _vow_failure(a.result, a.message))
+
+    async def resume(self, a: Resume) -> None:
+        # The shared C pump reports this as `yielded` before dispatch; keep
+        # the exhaustive generated handler complete for direct callers.
+        _ = a
+
+
+async def _run_action(host, action: HostAction) -> None:
+    await dispatch(action, host.action_handlers)

glowcap/_archive_contract.py

@@ -0,0 +1,25 @@
+"""Pre-call compatibility check for separately loaded FFI archives."""
+
+from __future__ import annotations
+
+import ctypes
+from collections.abc import Callable
+from typing import Any
+
+
+def require_archive_fingerprint(resolve: Callable[[], Any], stem: str, expected: int) -> None:
+    """Resolve and compare one archive fingerprint before ordinary use."""
+    try:
+        read = resolve()
+    except AttributeError as error:
+        raise RuntimeError(
+            f"{stem}: missing archive fingerprint; rebuild the FFI libraries from this checkout"
+        ) from error
+    read.argtypes = []
+    read.restype = ctypes.c_uint64
+    actual = int(read())
+    if actual != expected:
+        raise RuntimeError(
+            f"{stem}: callable surface does not match this binding "
+            f"(expected {expected:016x}, got {actual:016x}); rebuild the FFI libraries"
+        )