pulse-beacon 0.2.2__py3-none-any.whl

inventzia/pulse/beacon/__init__.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-beacon.
+#
+# pulse-beacon is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""pulse-beacon: the event-driven engine core and in-process cross-language bridge.
+
+See :mod:`inventzia.pulse.beacon.core` for the public engine API (actor / gateway
+bases, channel, logging facade).
+
+``inventzia`` and ``inventzia.pulse`` are PEP 420 namespace packages shared with
+pulse-data; from here inward the packages are regular packages with deliberate
+exports.
+"""

inventzia/pulse/beacon/_runtime/__init__.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-beacon.
+#
+# pulse-beacon is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""Carrier package for the wheel-bundled Beacon runtime jar.
+
+A *regular* package (unlike the PEP 420 namespace packages above it) so it can
+hold ``pulse-beacon-runtime.jar`` as package data, discoverable at runtime via
+``importlib.resources`` — see ``crosslanguage.jpype_host.bundled_runtime_jar``.
+
+The jar is a build artifact produced by ``pulse-beacon/build-runtime-jar.sh``
+(Maven ``-Pruntime-jar`` shade); it is not committed to source control.
+"""

inventzia/pulse/beacon/core/__init__.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-beacon.
+#
+# pulse-beacon is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""pulse-beacon engine core: actor / gateway bases, channel, and the logging facade.
+
+    from inventzia.pulse.beacon.core import BeaconActor, BeaconGateway
+
+Deliberately import-light — none of these pull the JVM bridges. Import the
+Python-host (``crosslanguage.jpype_host``) or Java-host (``crosslanguage.jep_host``)
+machinery from its own module only when you need it.
+"""
+
+from inventzia.pulse.beacon.core.actor import BeaconActor
+from inventzia.pulse.beacon.core.channel import BeaconChannel
+from inventzia.pulse.beacon.core.gateway import BeaconGateway
+from inventzia.pulse.beacon.core.reporter import (
+    CallbackReporter,
+    ComponentReporter,
+    LoggingReporter,
+    Reporter,
+    ReportLevel,
+)
+
+__all__ = [
+    "BeaconActor",
+    "BeaconGateway",
+    "BeaconChannel",
+    "Reporter",
+    "ReportLevel",
+    "LoggingReporter",
+    "CallbackReporter",
+    "ComponentReporter",
+]

inventzia/pulse/beacon/core/actor.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-beacon.
+#
+# pulse-beacon is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""
+Base class for a consumer/strategy actor implemented in Python.
+
+The Python mirror of the Java ``AbstractActor``: a reactive component that
+receives events on the topics it subscribes to and may publish new events back
+onto the bus. It is pure Python and JVM-agnostic — it never imports a JVM
+bridge. The cross-language streamer drives ``on_startup`` / ``on_event`` /
+``on_shutdown`` from the foreign side, and :meth:`publish` goes out through a bound
+:class:`~inventzia.pulse.beacon.core.channel.BeaconChannel`.
+"""
+
+from abc import ABC, abstractmethod
+
+from inventzia.pulse.beacon.core.reporter import ComponentReporter
+from inventzia.pulse.data.datum.datum import Datum
+
+
+class BeaconActor(ABC):
+    """A reactive actor. Override :meth:`on_event` (and optionally the lifecycle hooks)."""
+
+    def __init__(self, name: str):
+        self.name = name
+        self.log = ComponentReporter(name)
+        self._channel = None  # bound at registration; see bind()
+
+    # ------------------------------------------------------------------
+    # Binding — the outbound bus, set before the run starts
+    # ------------------------------------------------------------------
+
+    def bind(self, channel) -> None:
+        """Bind the outbound :class:`BeaconChannel` this actor publishes through."""
+        self._channel = channel
+
+    def publish(self, topic_name: str, datum: Datum) -> None:
+        """Publish a datum onto the bus via the bound channel."""
+        if self._channel is None:
+            raise RuntimeError(
+                f"actor '{self.name}' published before being bound to a channel")
+        self._channel.publish(topic_name, datum)
+
+    # ------------------------------------------------------------------
+    # Lifecycle + inbound — override as needed
+    # ------------------------------------------------------------------
+
+    def on_startup(self, time_millis: int) -> None:
+        """Called once when the run begins, at the start time. Default: no-op."""
+
+    @abstractmethod
+    def on_event(self, topic_name: str, datum: Datum) -> None:
+        """Handle one event delivered on ``topic_name``."""
+
+    def on_shutdown(self, time_millis: int) -> None:
+        """Called once when the run ends. Default: no-op."""

inventzia/pulse/beacon/core/channel.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-beacon.
+#
+# pulse-beacon is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""
+The outbound bus for a Python component.
+
+The Python mirror of the bus an ``AbstractActor`` is bound to: it carries a
+datum the component wants to emit back onto the engine. It wraps the Java
+cross-language endpoint and calls its ``publishTagged(topicName, taggedJson)``,
+serialising the datum to the self-describing tagged envelope first. The
+component never sees the endpoint or any JSON — only :meth:`publish`.
+"""
+
+from inventzia.pulse.data.datum.codec import to_tagged_json
+from inventzia.pulse.data.datum.datum import Datum
+
+
+class BeaconChannel:
+    """Publishes a datum onto the bus through the Java cross-language endpoint."""
+
+    def __init__(self, endpoint):
+        # endpoint: the Java CrossLanguageActor (a JPype/JEP proxy) exposing
+        # publishTagged(str, str). Held opaquely so this class stays JVM-agnostic.
+        self._endpoint = endpoint
+
+    def publish(self, topic_name: str, datum: Datum) -> None:
+        """Serialise ``datum`` and publish it on ``topic_name``."""
+        self._endpoint.publishTagged(topic_name, to_tagged_json(datum))

inventzia/pulse/beacon/core/crosslanguage/__init__.py

@@ -0,0 +1,16 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-beacon.
+#
+# pulse-beacon is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""In-process cross-language bridge: the JVM-agnostic streamer plus the JPype
+(Python-host) and JEP (Java-host) bootstraps.
+
+Kept import-light on purpose — the ``jpype_host`` / ``jep_host`` modules pull
+heavy or native dependencies, so import the specific host you need rather than
+this package.
+"""

inventzia/pulse/beacon/core/crosslanguage/cross_language_streamer.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-beacon.
+#
+# pulse-beacon is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""
+The one control loop that bridges a Python component to its Java counterpart.
+
+This is the single piece of streaming logic, written once and used unchanged in
+both embedding directions: under JPype it runs on a Python-owned thread, under
+JEP on the thread the JVM created for it. It only *calls* the Java endpoint
+(``takeNext`` / ``ackDone`` for a consumer, ``offerNext`` / ``finish`` for a
+source) and the Python component (``produce`` / ``on_event`` / lifecycle), so
+nothing here is JVM-specific.
+
+Two loop flavours mirror the two roles:
+
+* :meth:`run_consume` — engine → Python. Drains events the engine dispatched,
+  routes each to the component, and acks (which releases the engine's dispatch
+  thread, the determinism handshake).
+* :meth:`run_produce` — Python → engine. Pulls the source's ``produce`` stream
+  and offers each event to the Java gateway, which blocks until it has been
+  emitted through the time-machine write permit.
+
+A bidirectional gateway runs both loops on two threads — the modern form of the
+old ``run_incoming_data`` / ``run_outgoing_data`` pair.
+"""
+
+import traceback
+
+from inventzia.pulse.beacon.core.dispatch import dispatch_consume, event_kind
+from inventzia.pulse.beacon.core.reporter import ComponentReporter
+from inventzia.pulse.data.datum.codec import to_tagged_json
+
+_log = ComponentReporter("streamer")
+
+
+class CrossLanguageStreamer:
+    """Drives one Python component against its Java cross-language endpoint."""
+
+    def __init__(self, endpoint, component, channel=None):
+        # endpoint: the Java CrossLanguageActor / CrossLanguageGateway proxy.
+        self._endpoint = endpoint
+        self._component = component
+        # If a channel is supplied and the component can publish, bind it now so
+        # on_event handlers may publish during the consume loop.
+        if channel is not None and hasattr(component, "bind"):
+            component.bind(channel)
+
+    def run_consume(self) -> None:
+        """Engine → Python: drain, route, ack — until an END event arrives."""
+        while True:
+            event = self._endpoint.takeNext()  # blocks
+            if event_kind(event) == "END":
+                break
+            try:
+                dispatch_consume(self._component, event)
+            except Exception:
+                # A failing handler must not kill the streamer: the engine's
+                # dispatch thread is blocked waiting for our ack, so dying here
+                # would deadlock the run. Log and carry on.
+                _log.severe("error handling cross-language event\n" + traceback.format_exc())
+            finally:
+                self._endpoint.ackDone()  # release the engine's dispatch thread
+
+    def run_produce(self, on_error=None) -> None:
+        """Python → engine: offer each produced event; the gateway paces us via the permit.
+
+        ``finish()`` runs in a ``finally`` so that a producer which raises (e.g. a
+        source that cannot open its input) or yields nothing still signals completion
+        to its Java gateway. Otherwise the engine's all-drivers barrier would wait on a
+        dead producer forever — a hang, not a fast failure.
+
+        ``on_error`` (optional) is invoked with the exception *before* the
+        ``finally`` runs, so a supervisor can react immediately: if the engine is
+        itself wedged (another driver also failed), ``finish()`` may block until the
+        engine is torn down, and waiting for it to return would defeat fast failure.
+        The exception still propagates after ``finish()`` for callers that rely on it.
+        """
+        try:
+            for topic_name, datum in self._component.produce():
+                self._endpoint.offerNext(topic_name, to_tagged_json(datum))  # blocks until accepted
+        except BaseException as exc:  # noqa: BLE001 — notify, then let it propagate
+            if on_error is not None:
+                try:
+                    on_error(exc)
+                except Exception:
+                    pass
+            raise
+        finally:
+            self._endpoint.finish()

inventzia/pulse/beacon/core/crosslanguage/jep_host.py

@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-beacon.
+#
+# pulse-beacon is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""
+Java-host (JEP) scaffold: a generic factory that runs a Python component's streamer.
+
+The mirror of :mod:`jpype_host`, for the opposite embedding direction. Under JPype
+a Python process boots the JVM; under JEP the **JVM is the host** and creates a
+CPython interpreter (one per streamer thread) via JEP. The Java launcher drives
+everything declaratively: it hands in the Java ``CrossLanguage*`` endpoint, the
+*fully-qualified name* of the Python component type, and its constructor args, and
+picks which streamer loop to run.
+
+This module is a **factory, not an example** — it knows no component names and
+imports nothing from the ``examples`` package. The two entry points are named
+after the two streamer loops, which is what they actually run and is orthogonal to
+component type:
+
+* :func:`run_consume` — engine → Python. Used for an **Actor** (which consumes via
+  ``on_event`` and may publish back) and for a **Gateway** in its **sink** role.
+* :func:`run_produce` — Python → engine. Used for a **Gateway** in its **source**
+  role (which yields from ``produce``).
+
+The component itself (any ``BeaconActor`` / ``BeaconGateway``, or a purpose-built
+subclass such as a recording actor for parity) is constructed by fully-qualified
+name — the example-specific choice of *which* types with *which* args lives on the
+Java side, not here.
+
+Everything below the factory — the components, ``dispatch``, and the streamer — is
+JVM-agnostic and identical to the JPype path; only *who starts whom* differs. Each
+``run_*`` blocks on the streamer loop until it ends (``END`` for consume, source
+exhaustion for produce), so the calling Java thread *is* the streamer thread —
+which is what JEP requires, since an interpreter is bound to its creating thread.
+"""
+
+import importlib
+
+from inventzia.pulse.beacon.core.channel import BeaconChannel
+from inventzia.pulse.beacon.core.crosslanguage.cross_language_streamer import CrossLanguageStreamer
+
+
+def _instantiate(type_fqn: str, args):
+    """Import ``pkg.module.ClassName`` and construct it with ``args``.
+
+    ``args`` is whatever the Java launcher handed in (typically a ``java.util.List``
+    of constructor arguments); it is materialised to a Python list so both plain
+    values and Java-object arguments (e.g. a parity sink) pass straight through.
+    """
+    module_path, _, class_name = type_fqn.rpartition(".")
+    if not module_path:
+        raise ValueError(
+            f"component type must be a fully-qualified 'module.Class' name, got {type_fqn!r}")
+    cls = getattr(importlib.import_module(module_path), class_name)
+    return cls(*list(args))
+
+
+def run_consume(endpoint, type_fqn, args, publishes=False):
+    """Build ``type_fqn(*args)`` and drive its consume loop (engine → Python) until END.
+
+    :param endpoint: the Java ``CrossLanguageActor`` / sink ``CrossLanguageGateway`` proxy.
+    :param type_fqn: fully-qualified name of the Python Actor / sink-Gateway class.
+    :param args: constructor arguments (a Java list; Java objects pass through).
+    :param publishes: if true, bind a :class:`BeaconChannel` so the component can
+        publish back onto the bus (an Actor with a ``Pub`` role, e.g. an echo actor).
+    """
+    component = _instantiate(type_fqn, args)
+    channel = BeaconChannel(endpoint) if publishes else None
+    CrossLanguageStreamer(endpoint, component, channel).run_consume()
+
+
+def run_produce(endpoint, type_fqn, args):
+    """Build ``type_fqn(*args)`` and drive its produce loop (Python → engine) until exhausted.
+
+    :param endpoint: the Java source ``CrossLanguageGateway`` proxy.
+    :param type_fqn: fully-qualified name of the Python source-Gateway class.
+    :param args: constructor arguments (a Java list; Java objects pass through).
+    """
+    component = _instantiate(type_fqn, args)
+    CrossLanguageStreamer(endpoint, component).run_produce()

inventzia/pulse/beacon/core/crosslanguage/jpype_host.py

@@ -0,0 +1,236 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-beacon.
+#
+# pulse-beacon is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""
+Python-host bootstrap: start an embedded JVM (via JPype) on the Beacon classpath.
+
+This is the only direction-specific piece for the Python-host launcher. The
+classpath is resolved in two ways, in order:
+
+  1. **Installed package (zero-config):** a single shaded *runtime jar* — Beacon
+     plus its ordinary Java dependencies — bundled inside the wheel at
+     ``inventzia.pulse.beacon._runtime``. Located via ``importlib.resources``, so
+     ``pip install pulse-beacon`` needs no staged jars, ``PYTHONPATH``, or Maven.
+  2. **Source checkout (dev):** the Maven-produced release jar set staged into
+     ``<pulse-beacon>/core/java/jars/`` (the module jar plus runtime deps).
+
+JPype finds the JVM itself from ``JAVA_HOME`` — a jar is not a JVM, so a JDK/JRE
+17+ must be present (see PackagingAndPublishingRelease.md §3). Everything above
+the bootstrap (actors, gateways, channel, dispatch, streamer) is JVM-agnostic
+and unchanged from the Java-host (JEP) path.
+"""
+
+import glob
+import os
+from pathlib import Path
+
+from inventzia.pulse.beacon.core.reporter import ComponentReporter
+
+_log = ComponentReporter("jpype-host")
+
+# The wheel-bundled shaded runtime jar (built by core/java `mvn -Pruntime-jar`
+# and copied here — see pulse-beacon/build-runtime-jar.sh).
+_RUNTIME_PACKAGE = "inventzia.pulse.beacon._runtime"
+_RUNTIME_JAR = "pulse-beacon-runtime.jar"
+
+
+def bundled_runtime_jar() -> Path | None:
+    """The shaded runtime jar bundled in the installed wheel, or ``None`` if absent.
+
+    Present in an installed/built package; absent in a bare source checkout that
+    hasn't run ``build-runtime-jar.sh`` (dev then falls back to the staged jars).
+    """
+    try:
+        from importlib.resources import files
+        res = files(_RUNTIME_PACKAGE).joinpath(_RUNTIME_JAR)
+        path = Path(str(res))
+        return path if path.is_file() else None
+    except (ModuleNotFoundError, FileNotFoundError, TypeError):
+        return None
+
+
+def default_jars_dir() -> Path:
+    """The staged release jars directory: ``<pulse-beacon>/core/java/jars``.
+
+    Source-checkout convenience only; for an installed package this is superseded
+    by the bundled runtime-jar discovery (:func:`bundled_runtime_jar`).
+    """
+    # .../pulse-beacon/src/inventzia/pulse/beacon/core/crosslanguage/jpype_host.py
+    # parents[6] is the pulse-beacon repo root.
+    beacon_root = Path(__file__).resolve().parents[6]
+    return beacon_root / "core" / "java" / "jars"
+
+
+def resolve_classpath(jars_dir=None) -> tuple[list[str], str]:
+    """Resolve the Beacon classpath: explicit dir, else bundled jar, else staged jars.
+
+    Returns ``(jars, source_description)``. Raises ``FileNotFoundError`` if none resolve.
+    """
+    if jars_dir is not None:
+        jars = sorted(glob.glob(str(Path(jars_dir) / "*.jar")))
+        if jars:
+            return jars, f"{len(jars)} jars from {jars_dir}"
+        raise FileNotFoundError(f"no jars in {jars_dir}")
+
+    bundled = bundled_runtime_jar()
+    if bundled is not None:
+        return [str(bundled)], f"bundled runtime jar {bundled}"
+
+    staged = default_jars_dir()
+    jars = sorted(glob.glob(str(staged / "*.jar")))
+    if jars:
+        return jars, f"{len(jars)} staged jars from {staged}"
+
+    raise FileNotFoundError(
+        f"no Beacon classpath found. Either install the package (bundled runtime jar), "
+        f"or build the staged jars into {staged} with pulse-beacon/build-runtime-jar.sh "
+        f"(or: cd core/java && mvn package -DskipTests && "
+        f"mvn dependency:copy-dependencies -DoutputDirectory=jars -DincludeScope=runtime && "
+        f"cp target/pulse-beacon-core-*.jar jars/)")
+
+
+def _normalize_classpath_entry(entry: str) -> str:
+    """Canonicalize a classpath entry for comparison (absolute path, OS-normalized case/sep)."""
+    return os.path.normcase(os.path.abspath(str(entry)))
+
+
+def _running_classpath_entries() -> set[str]:
+    """The normalized entries on the already-running JVM's ``java.class.path``."""
+    from jpype import JClass
+    raw = JClass("java.lang.System").getProperty("java.class.path") or ""
+    return {_normalize_classpath_entry(e) for e in str(raw).split(os.pathsep) if e}
+
+
+class TypeUniverseMismatch(RuntimeError):
+    """The Python and Java datum-type universes disagree; the bridge must not run.
+
+    Raised before any event flows, so a producer cannot emit an extension datum the
+    receiving runtime cannot decode (the SPI Phase 3 fail-fast gate).
+    """
+
+
+def start_jvm(jars_dir=None, verify=True, extra_classpath=None) -> None:
+    """Start the embedded JVM on the Beacon classpath, if not already running.
+
+    Classpath resolution order: explicit ``jars_dir`` → wheel-bundled runtime jar →
+    source-tree staged jars (see :func:`resolve_classpath`). ``extra_classpath`` (a list of
+    jar paths) is appended, so an extension jar contributing datum types via
+    ``META-INF/services`` is discovered by the Java ``ServiceLoader``. The JVM is located via
+    ``JAVA_HOME``; in the shared ``pulse`` conda env that is set automatically by the bundled
+    OpenJDK, so no manual export is needed; outside it, point ``JAVA_HOME`` at any JDK 17+.
+    Idempotent.
+
+    If ``verify`` (default), the Python and Java datum-type universes are compared once
+    the JVM is up, before any event flows, and a mismatch raises
+    :class:`TypeUniverseMismatch` (see :func:`verify_type_universe`).
+
+    **Reusing an existing JVM.** If a JVM is already running (a prior ``start_jvm``, a re-run
+    notebook cell, a retry after a failed verification, or a host application that booted the
+    JVM), this does not silently no-op: verification (when ``verify``) still runs, so a
+    mismatch present now is caught rather than slipping through just because the JVM started
+    earlier. And because a running JVM's classpath cannot be changed, any requested classpath
+    additions (``jars_dir`` / ``extra_classpath``) that are not already on it raise a
+    :class:`RuntimeError` rather than being silently ignored.
+    """
+    import jpype
+
+    if jpype.isJVMStarted():
+        # A running JVM's classpath is fixed. If the caller asked to add jars that are not
+        # already on it, they cannot be honored — fail loudly instead of silently dropping them.
+        if jars_dir is not None or extra_classpath:
+            requested = list(resolve_classpath(jars_dir)[0]) if jars_dir is not None else []
+            requested += [str(p) for p in (extra_classpath or [])]
+            on_classpath = _running_classpath_entries()
+            missing = [j for j in requested if _normalize_classpath_entry(j) not in on_classpath]
+            if missing:
+                raise RuntimeError(
+                    "JVM already running; its classpath cannot be changed, but start_jvm() was "
+                    f"asked to add jars that are not on it: {missing}. Start the JVM once with the "
+                    "full classpath (including every extension jar) before any other JPype use.")
+        _log.large_info("JVM already running; reusing it")
+        # Verification must still run on reuse (notebooks, retries, host-app JVMs): a mismatch
+        # now must not pass just because the JVM was started by an earlier call.
+        if verify:
+            verify_type_universe()
+        return
+
+    jars, source = resolve_classpath(jars_dir)
+    if extra_classpath:
+        jars = list(jars) + [str(p) for p in extra_classpath]
+        source += f" + {len(extra_classpath)} extension jar(s)"
+
+    if "JAVA_HOME" not in os.environ:
+        # A jar is not a JVM. In the `pulse` env JAVA_HOME is set automatically;
+        # outside it, set it explicitly.
+        raise EnvironmentError(
+            "JAVA_HOME is not set; run in the `pulse` conda env, or point it at a JDK 17+")
+
+    # convertStrings=True: Java String returns (topic names, tagged JSON) come
+    # back as native Python str, so json.loads / str ops work without wrapping.
+    jpype.startJVM(classpath=jars, convertStrings=True)
+    _log.info(f"JVM started ({source})")
+    if verify:
+        verify_type_universe()
+
+
+def _java_registry():
+    from jpype import JClass
+    return JClass("com.inventzia.pulse.data.datum.DatumTypeRegistry").defaultRegistry()
+
+
+def _py_type_map(registry) -> dict:
+    return {tid: (ver, fp) for pi in registry.providers() for (tid, ver, fp) in pi.entries}
+
+
+def _java_type_map(registry) -> dict:
+    return {str(e.typeId()): (int(e.typeVersion()), str(e.fingerprint()))
+            for pi in registry.providers() for e in pi.entries()}
+
+
+def verify_type_universe(py_registry=None, java_registry=None) -> str:
+    """Compare the Python and Java composite datum-type fingerprints; fail fast on mismatch.
+
+    Returns the shared fingerprint on success. Raises :class:`TypeUniverseMismatch` if the
+    two differ (naming the missing or incompatible types), or if either side is unverifiable
+    (a provider without a manifest), which is treated as fail-closed. Defaults to each
+    runtime's process-wide registry; explicit registries are accepted for testing.
+    """
+    from inventzia.pulse.data.datum.registry import default_registry
+
+    py_reg = py_registry if py_registry is not None else default_registry()
+    java_reg = java_registry if java_registry is not None else _java_registry()
+
+    py_fp = py_reg.fingerprint()
+    jfp = java_reg.fingerprint()
+    java_fp = str(jfp) if jfp is not None else None
+
+    if py_fp is None or java_fp is None:
+        py_unv = list(py_reg.unverifiable_providers())
+        java_unv = [str(x) for x in java_reg.unverifiableProviders()]
+        raise TypeUniverseMismatch(
+            "datum-type universe is unverifiable (a provider has no manifest): "
+            f"python unverifiable={py_unv}, java unverifiable={java_unv}")
+
+    if py_fp != java_fp:
+        pym, jvm = _py_type_map(py_reg), _java_type_map(java_reg)
+        diffs = []
+        for tid in sorted(set(pym) | set(jvm)):
+            p, j = pym.get(tid), jvm.get(tid)
+            if p is None:
+                diffs.append(f"  {tid}: only in Java")
+            elif j is None:
+                diffs.append(f"  {tid}: only in Python")
+            elif p != j:
+                diffs.append(f"  {tid}: differs (python v{p[0]}/{p[1][:8]}, java v{j[0]}/{j[1][:8]})")
+        raise TypeUniverseMismatch(
+            f"cross-language datum-type universe mismatch (python={py_fp[:12]}, java={java_fp[:12]}):\n"
+            + "\n".join(diffs))
+
+    _log.large_info(lambda: f"type universe verified: {py_fp[:12]}")
+    return py_fp

inventzia/pulse/beacon/core/dispatch.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-beacon.
+#
+# pulse-beacon is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""
+Routing of one inbound cross-language event to a component's callbacks.
+
+A ``CrossLanguageEvent`` crossing the boundary carries a transport-level
+``kind`` (``DATA`` / ``START`` / ``STOP`` / ``END``). :func:`dispatch_consume`
+maps a single event to the right component callback, decoding the
+self-describing tagged JSON to a native pulse-data model for ``DATA`` events so
+the component only ever sees a typed datum, never JSON. ``END`` is the
+streamer loop's concern, not this function's.
+"""
+
+from inventzia.pulse.data.datum.codec import from_tagged_json
+
+
+def event_kind(event) -> str:
+    """The kind name of a cross-language event as a plain string (e.g. ``"DATA"``)."""
+    # event.kind() is a Java CrossLanguageEvent.Kind enum constant under the
+    # in-process bridge; .name() yields its string name.
+    return event.kind().name()
+
+
+def dispatch_consume(component, event) -> None:
+    """Route one inbound event to ``component``'s lifecycle / on_event callbacks."""
+    kind = event_kind(event)
+    if kind == "DATA":
+        datum = from_tagged_json(event.taggedJson())
+        component.on_event(event.topicName(), datum)
+    elif kind == "START":
+        component.on_startup(event.time())
+    elif kind == "STOP":
+        component.on_shutdown(event.time())
+    # END: handled by the streamer loop (terminates it); nothing to dispatch.

inventzia/pulse/beacon/core/examples/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later OR LicenseRef-Inventzia-Commercial
+# Copyright (c) 2013-2026 Magrino Bini, Paola Apruzzese, Inventzia Science and Technology Ltd.
+#
+# This file is part of pulse-beacon.
+#
+# pulse-beacon is dual-licensed:
+#   - Under the GNU Affero General Public License v3.0 or later (see LICENSE-AGPL-3.0).
+#   - Under a commercial license (see LICENSE-COMMERCIAL.txt).
+#     Contact operations@inventzia.com.
+"""Runnable cross-language examples (Python-host JPype and Java-host JEP).
+
+Import-light: each example module boots the JVM and imports the bridge itself,
+so run a module directly (``python -m inventzia.pulse.beacon.core.examples.<name>``)
+rather than importing this package.
+"""