nyrobrain 0.1.0__tar.gz

nyrobrain-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+node_modules/
+.env*
+.worktrees
+.DS_Store
+.claude/
+graphify-out/
+
+# Generated KB artifacts — never commit (mcp writes these under a
+# workspace's .nyrobrain/kb/ at runtime; the template copies are stray).
+template/kb.sqlite*
+template/kb-graph.json
+template/.nyrobrain/
+
+# Cleaned template staged into the desktop app bundle at build time
+# (apps/desktop/scripts/stage-template.sh).
+apps/desktop/src-tauri/resources/template/
+.worktrees/
+
+# Test coverage output (bun --coverage-dir, junit, cobertura). Generated by
+# `bun run test:coverage` and uploaded as CI artifacts; never committed.
+coverage/
+
+# Python (py/ — the nyrobrain library). `coverage/` above already covers
+# py/coverage/. These are uv / pytest / ruff / mypy local caches.
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.uv-cache/
+.coverage
+.coverage.*
+.hypothesis/
+
+# Run output from the replay, paper, live and soak drivers (`--out`). These are
+# measurements of one moment on one machine — a summary, a parquet series and a
+# soak CSV — and the findings that matter are written up in the map's tickets
+# instead. A three-hour soak's series is also large enough to be worth keeping
+# out of the history.
+py/runs/

nyrobrain-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

nyrobrain-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.5
+Name: nyrobrain
+Version: 0.1.0
+Summary: Nyrobrain libraries. nyrobrain.execution translates portfolio signals into exchange orders.
+Author-email: Marcus Lee <marcuslee@balaenaquant.com>
+License: Proprietary
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.13
+Provides-Extra: aegis
+Requires-Dist: bq-nats-client>=0.1.6; extra == 'aegis'
+Provides-Extra: execution
+Requires-Dist: nautilus-trader==2.0.0rc4; extra == 'execution'
+Requires-Dist: pandas>=2.2; extra == 'execution'
+Requires-Dist: pyarrow>=17; extra == 'execution'
+Provides-Extra: prime
+Requires-Dist: httpx>=0.27; extra == 'prime'
+Description-Content-Type: text/markdown
+
+# nyrobrain
+
+Nyrobrain Python libraries.
+
+- `nyrobrain.execution` — translates portfolio signals (a target weight per
+  symbol) into orders at the exchange, on top of `nautilus_trader`.
+
+## What it is for
+
+A portfolio says *hold 25% of the book in BTC*. Something has to turn that into
+orders, against whatever is already held and whatever is already working, and
+keep doing it as the price moves and the target changes — without ever buying
+past the target. That last clause is the whole library. The failure it exists to
+prevent is an OMS that re-sends a delta it has already sent and walks a position
+away from its target.
+
+## You write the driver
+
+The library does not ship one. It ships the executor, the guards, the report and
+the pieces that are dangerous to get wrong; assembling them into a running
+system is your code, because that is where your choices live.
+
+Start from [`examples/oms.py`](src/nyrobrain/execution/examples/oms.py)
+— one script, three modes, copy it and change it:
+
+    python oms.py --mode backtest --signals signals.jsonl --candles ~/candles
+    python oms.py --mode paper --minutes 10
+    python oms.py --mode live  --minutes 10 --environment demo
+
+The executor, the guards and the report are identical in all three. That is the
+point: a difference in behaviour between two modes is the venue, not the
+harness.
+
+## Two surfaces
+
+**Decisions** — `nyrobrain.execution`. Sizing, the delta, the guards, the
+placement protocol. Imports no nautilus and installs without it, so you can
+reason about a target without an engine in the process. A placement strategy you
+write never imports nautilus either.
+
+**Assembly** — `nyrobrain.execution.driver`, `.backtest`, `.credentials`,
+`.venue`, `.runner`, `.report`. Nautilus all the way through, because building a
+node cannot be anything else.
+
+## Examples
+
+Runnable, shipped in the package, and executed by the test suite so they cannot
+rot. Read them in order:
+
+    python -m nyrobrain.execution.examples.sizing_a_target       # weight -> target -> delta
+    python -m nyrobrain.execution.examples.over_delivery_guard   # the invariant, and what it refuses
+    python -m nyrobrain.execution.examples.your_own_placement    # a placement strategy, no venue needed
+
+Then [`examples/README.md`](src/nyrobrain/execution/examples/README.md) for the
+driver itself.
+
+## Local development
+
+    uv sync --all-extras
+    uv run pytest
+
+`soak` is ours rather than yours — a long-run diagnostic for validating the
+executor over hours, not part of the driver story:
+
+    uv run python -m nyrobrain.execution.soak --hours 3 --environment demo
+
+## Design maps
+
+Built with the wayfinder method: numbered decision tickets under a map, worked
+one at a time. Each records not just what was decided but what was measured to
+decide it.
+
+- [`.scratch/nyrobrain-execution/map.md`](../.scratch/nyrobrain-execution/map.md)
+  — the arithmetic, the guards and the placement seam.
+- [`.scratch/nyrobrain-execution-runners/map.md`](../.scratch/nyrobrain-execution-runners/map.md)
+  — driving it from a `BacktestEngine` and a sandbox.
+- [`.scratch/nyrobrain-execution-live/map.md`](../.scratch/nyrobrain-execution-live/map.md)
+  — against a real venue on Bybit demo, and the nautilus 2 migration.

nyrobrain-0.1.0/README.md

@@ -0,0 +1,78 @@
+# nyrobrain
+
+Nyrobrain Python libraries.
+
+- `nyrobrain.execution` — translates portfolio signals (a target weight per
+  symbol) into orders at the exchange, on top of `nautilus_trader`.
+
+## What it is for
+
+A portfolio says *hold 25% of the book in BTC*. Something has to turn that into
+orders, against whatever is already held and whatever is already working, and
+keep doing it as the price moves and the target changes — without ever buying
+past the target. That last clause is the whole library. The failure it exists to
+prevent is an OMS that re-sends a delta it has already sent and walks a position
+away from its target.
+
+## You write the driver
+
+The library does not ship one. It ships the executor, the guards, the report and
+the pieces that are dangerous to get wrong; assembling them into a running
+system is your code, because that is where your choices live.
+
+Start from [`examples/oms.py`](src/nyrobrain/execution/examples/oms.py)
+— one script, three modes, copy it and change it:
+
+    python oms.py --mode backtest --signals signals.jsonl --candles ~/candles
+    python oms.py --mode paper --minutes 10
+    python oms.py --mode live  --minutes 10 --environment demo
+
+The executor, the guards and the report are identical in all three. That is the
+point: a difference in behaviour between two modes is the venue, not the
+harness.
+
+## Two surfaces
+
+**Decisions** — `nyrobrain.execution`. Sizing, the delta, the guards, the
+placement protocol. Imports no nautilus and installs without it, so you can
+reason about a target without an engine in the process. A placement strategy you
+write never imports nautilus either.
+
+**Assembly** — `nyrobrain.execution.driver`, `.backtest`, `.credentials`,
+`.venue`, `.runner`, `.report`. Nautilus all the way through, because building a
+node cannot be anything else.
+
+## Examples
+
+Runnable, shipped in the package, and executed by the test suite so they cannot
+rot. Read them in order:
+
+    python -m nyrobrain.execution.examples.sizing_a_target       # weight -> target -> delta
+    python -m nyrobrain.execution.examples.over_delivery_guard   # the invariant, and what it refuses
+    python -m nyrobrain.execution.examples.your_own_placement    # a placement strategy, no venue needed
+
+Then [`examples/README.md`](src/nyrobrain/execution/examples/README.md) for the
+driver itself.
+
+## Local development
+
+    uv sync --all-extras
+    uv run pytest
+
+`soak` is ours rather than yours — a long-run diagnostic for validating the
+executor over hours, not part of the driver story:
+
+    uv run python -m nyrobrain.execution.soak --hours 3 --environment demo
+
+## Design maps
+
+Built with the wayfinder method: numbered decision tickets under a map, worked
+one at a time. Each records not just what was decided but what was measured to
+decide it.
+
+- [`.scratch/nyrobrain-execution/map.md`](../.scratch/nyrobrain-execution/map.md)
+  — the arithmetic, the guards and the placement seam.
+- [`.scratch/nyrobrain-execution-runners/map.md`](../.scratch/nyrobrain-execution-runners/map.md)
+  — driving it from a `BacktestEngine` and a sandbox.
+- [`.scratch/nyrobrain-execution-live/map.md`](../.scratch/nyrobrain-execution-live/map.md)
+  — against a real venue on Bybit demo, and the nautilus 2 migration.

nyrobrain-0.1.0/justfile

@@ -0,0 +1,5 @@
+build:
+    uv run hatch build
+
+publish:
+    uv publish

nyrobrain-0.1.0/pyproject.toml

@@ -0,0 +1,109 @@
+[project]
+name = "nyrobrain"
+version = "0.1.0"
+description = "Nyrobrain libraries. nyrobrain.execution translates portfolio signals into exchange orders."
+readme = "README.md"
+license = { text = "Proprietary" }
+authors = [{ name = "Marcus Lee", email = "marcuslee@balaenaquant.com" }]
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+# Floor is 3.13 to match adrs, which migrates in later as a sibling subpackage;
+# ceiling is nautilus_trader's (`>=3.12,<3.15`). Supporting 3.12 would buy
+# nothing and would have to be given up the moment adrs lands.
+requires-python = ">=3.13,<3.15"
+# The base install is deliberately dependency-free: importing `nyrobrain` must
+# never drag in an engine or a transport. Everything real lives behind an extra.
+dependencies = []
+
+[project.optional-dependencies]
+execution = ["nautilus_trader==2.0.0rc4", "pandas>=2.2", "pyarrow>=17"]
+# The HTTP client the Prime signal source polls with. Behind an extra so the
+# decision surface, and every test of it, needs no transport installed.
+prime = ["httpx>=0.27"]
+# The gRPC client the Aegis sink publishes through. Not a NATS protocol client:
+# publishers reach JetStream via a sidecar authenticated by API key and hold no
+# NATS credentials, which is also why portfolio targets deliberately live in a
+# different account. Behind an extra for the same reason `prime` is — the
+# decision surface builds the payloads and needs no transport to be tested.
+aegis = ["bq-nats-client>=0.1.6"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3",
+    "pytest-cov>=6.0",
+    "hypothesis>=6.120",
+    "mypy>=1.13",
+    "ruff>=0.8",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nyrobrain"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Coverage and report flags are NOT in addopts: the local run stays fast so it
+# actually gets run. CI adds them explicitly.
+addopts = "-q --strict-markers --strict-config"
+filterwarnings = [
+    # A warning raised by this library is a defect, and much cheaper to adopt
+    # now than to retrofit.
+    "error",
+    # Except when it is not ours. nautilus's BacktestEngine calls
+    # `Timestamp.utcnow` internally, which pandas 4 deprecates. We cannot fix it
+    # and will not skip running the engine over it; narrow it to the one message
+    # so everything else still fails.
+    "ignore:Timestamp.utcnow is deprecated:",
+    # Same rule, second instance: constructing a `TradingNode` calls
+    # `asyncio.get_event_loop_policy`, which Python 3.14 deprecates. Theirs to
+    # fix, and not a reason to stop building nodes in tests.
+    "ignore:'asyncio.get_event_loop_policy' is deprecated:",
+]
+
+[tool.coverage.run]
+source = ["nyrobrain"]
+branch = true
+
+[tool.ruff]
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle
+    "F",    # pyflakes
+    "I",    # isort
+    "UP",   # pyupgrade
+    "B",    # bugbear
+    "SIM",  # simplify
+    "RUF",
+]
+
+[tool.mypy]
+python_version = "3.13"
+packages = ["nyrobrain"]
+strict = true
+warn_unreachable = true
+# Scoped to third parties rather than global. A global
+# `ignore_missing_imports` also silences a *first-party* module that does not
+# exist: a stale `from nyrobrain.execution.backtest import ...` type-checked
+# clean while failing at import, which is precisely the failure the examples
+# are type-checked to prevent.
+# Every nautilus base class is Cython, so mypy sees it as `Any` and this check
+# can never pass for any nautilus subclass - Data here, Strategy shortly. It
+# carries no signal for us, and the alternative is a growing list of per-module
+# ignores. Everything else stays strict.
+disallow_subclassing_any = false
+
+[[tool.mypy.overrides]]
+# Nautilus ships partial stubs; pandas/pyarrow/hypothesis ship none we rely on.
+module = ["nautilus_trader.*", "pandas.*", "pyarrow.*", "hypothesis.*"]
+ignore_missing_imports = true

nyrobrain-0.1.0/src/nyrobrain/__init__.py

@@ -0,0 +1,7 @@
+"""Nyrobrain Python libraries.
+
+This package is a namespace and deliberately exports nothing. Siblings are
+expected alongside `nyrobrain.execution` — adrs migrates in later under the same
+brand — so importing `nyrobrain` must never pull an engine, a transport or a
+research stack into the process. Import the subpackage you want.
+"""

nyrobrain-0.1.0/src/nyrobrain/execution/CONTEXT.md

@@ -0,0 +1,109 @@
+# nyrobrain.execution
+
+The shared language of the execution library. A glossary, not a spec: it fixes what each word means so that the library, the portfolio that feeds it, and the dashboards that watch it all use it the same way.
+
+## Language
+
+### The instruction
+
+**Signal**:
+One portfolio's complete target state at one instant: a target weight for every asset it holds. The whole truth, never a change set — so applying the same signal twice leaves the portfolio where applying it once did.
+_Avoid_: Order, instruction, update, delta, rebalance
+
+**Target weight**:
+The share of a portfolio's notional budget an asset should occupy, signed for direction. Positive is long, negative is short. It says what to hold, never what to trade.
+_Avoid_: Allocation, size, position size, exposure
+
+**Gross exposure**:
+The sum of a signal's target weights ignoring their signs — the total notional a portfolio wants deployed. A signal is invalid above 1. Distinct from net exposure, which cancels longs against shorts and therefore bounds direction rather than leverage.
+_Avoid_: Total exposure, leverage, sum of weights
+
+**Flat**:
+Holding nothing in an asset. A target weight of zero and an asset's absence from a signal both mean flat; a correct publisher states the zero, and an absence is a defect worth alerting on.
+_Avoid_: Closed, exited, zeroed, neutral
+
+**Target**:
+The position an asset should hold, in base units, implied by its target weight and the portfolio's budget, leverage and the current price. What we want; never what we do about it.
+_Avoid_: Desired, goal, wanted position, ideal
+
+**Actual**:
+The position held at the venue. Read, never remembered — a figure the library keeps for itself between ticks is a figure that can go stale, and stale actuals are what made an OMS buy without end.
+_Avoid_: Current, held, exchange position, real position
+
+**Working**:
+Every order of ours that could still fill, counted toward the position we are already committed to. Includes orders sent but not yet acknowledged: a quantity in flight has been committed even though nothing has filled and the venue has not replied.
+_Avoid_: Open orders, pending, resting, outstanding, in-flight
+
+**Delta**:
+What remains to be traded for an asset: its target less its actual less its working. Derived afresh each tick, never carried forward, so an under-traded tick corrects itself and a repeated tick does nothing.
+_Avoid_: Diff, gap, remainder, adjustment, order size
+
+**Placement**:
+Deciding how to work a delta into the book — how many orders, at what prices, amended or cancelled when. Owned by the user, who may substitute their own. It is told the quantity to trade and never the position, so that position arithmetic cannot re-enter through it.
+_Avoid_: Execution, order strategy, routing, slicing
+
+**Driver**:
+The script that assembles an engine or a node, attaches the executor, runs it for a while and writes the report. Owned by the user, like placement — the library ships examples of one, never one of its own. What distinguishes it from placement is scope rather than ownership: placement decides how a single delta reaches the book, a driver decides which venue, which mode, which symbols and for how long.
+_Avoid_: Runner, entrypoint, harness, main
+
+**Committed**:
+The quantity we already stand behind for an asset — what our live orders would add to the position if every one of them filled. Placement is judged on how much it changes this, never on the size of the orders it returns: repricing an order changes its price and commits nothing, which is what makes it legal when there is nothing left to trade.
+_Avoid_: Exposure, pending, allocated, reserved
+
+**Over-delivery**:
+Placement returning orders that would trade further than the delta, or in the opposite direction. Always a defect: under-trading is bounded by doing nothing and corrects next tick, while over-trading has no ceiling and compounds.
+_Avoid_: Overshoot, overfill, excess
+
+**Base asset**:
+What a signal names — the underlying an alpha has a view on, such as `BTC`. Independent of any venue.
+_Avoid_: Ticker, symbol, instrument, coin
+
+**Symbol**:
+What a venue trades, such as `BTCUSDT`. One base asset maps to a different symbol on each venue; the mapping is configuration, never part of a signal.
+_Avoid_: Pair, instrument, market, asset
+
+**Sandbox**:
+Paper trading against live market data with simulated fills. Needs no exchange credentials, and is therefore not a venue — no order it produces exists anywhere, and its results are a simulation whose realism is a setting rather than a fact.
+_Avoid_: Paper, demo, testnet, simulation, dry run
+
+### Provenance and ordering
+
+**Publisher**:
+The process that computes a portfolio's target state and emits signals. It owns the portfolio's alphas and their aggregation; the library is only ever its consumer.
+_Avoid_: Producer, sender, portfolio process, upstream
+
+**Epoch**:
+A publisher process's identity — fixed for its lifetime and different after every restart. It exists so a restarted publisher, whose sequence has returned to zero, still outranks the stream it replaced.
+_Avoid_: Run id, generation, boot id, version
+
+**Sequence**:
+A signal's position within one epoch, increasing with each signal that publisher emits. Meaningless across epochs on its own.
+_Avoid_: Index, counter, offset, id
+
+**Supersede**:
+What a signal does to the last one applied when it is genuinely newer, judged on epoch and sequence together. A signal that does not supersede is inert rather than erroneous: redelivery is expected traffic.
+_Avoid_: Override, replace, win, update
+
+### Time and health
+
+**Expected gap**:
+How long a publisher says it will be before it speaks again, taken from its own aggregation cadence. Not the interval of the alphas it aggregates — those are usually far longer, and a deadline built on them would never fire.
+_Avoid_: Interval, period, frequency, cadence, alpha interval
+
+**Missed deadline**:
+The expected gap elapsing, plus grace, without a signal arriving. It describes the health of the feed, never the validity of a signal: one that arrives afterwards is still applied, and applying it is what clears the condition.
+_Avoid_: Timeout, stale signal, late signal, expired
+
+**Escalated**:
+The state a portfolio enters after several consecutive missed deadlines — its publisher is presumed gone rather than slow. Escalation stops new orders and cancels resting ones; it never exits positions, because a crash-looping process would then exit and rebuy in a loop, paying the spread each cycle.
+_Avoid_: Halted, stopped, paused, killed, panicked
+
+**Actionable**:
+Young enough to trade on. A signal can be the newest ever seen and still too old to act on, in which case it is not traded — a signal that stale means the publisher was broken, and guessing is worse than stopping.
+_Avoid_: Fresh, valid, current, live
+
+### Rejection
+
+**Invalid**:
+Untrustworthy, and therefore not applied at all. Rejection is always whole-signal: applying the sound part of a target state would leave a position the strategy never asked for and cannot reason about.
+_Avoid_: Malformed, bad, partial, unparseable

nyrobrain-0.1.0/src/nyrobrain/execution/__init__.py

@@ -0,0 +1,78 @@
+"""Order execution: portfolio signal in, exchange orders out.
+
+The library's job is target-position reconciliation. A signal names a target
+weight per symbol; this package decides what orders that implies against the
+position actually held at the venue, and places them.
+
+Nothing nautilus-shaped crosses this package's public boundary. Callers work in
+plain types — symbols as `str`, quantities and weights as `Decimal` — so the
+engine underneath stays an implementation detail and hooks stay testable without
+constructing framework objects.
+
+Public so far: the input type, and the sizing and guard arithmetic the executor
+is built on. The executor itself — the nautilus Strategy that drives these on a
+timer — arrives with the hook-surface and testing-surface tickets.
+"""
+
+from nyrobrain.execution.intake import Fetch, SignalSource
+from nyrobrain.execution.ladder import LadderConfig, TouchLadder
+from nyrobrain.execution.metrics import AegisMetrics, Fanout, Metric, MetricSink
+from nyrobrain.execution.placement import (
+    Action,
+    Amend,
+    Cancel,
+    Context,
+    Place,
+    Placement,
+    Resting,
+    UnknownOrder,
+    committed_change,
+    validate,
+)
+from nyrobrain.execution.signal import (
+    MAX_GROSS_EXPOSURE,
+    SCHEMA_VERSION,
+    InvalidSignal,
+    Signal,
+    parse_signal,
+)
+from nyrobrain.execution.target import (
+    OverDelivery,
+    check_intent,
+    round_price,
+    round_quantity,
+    target_quantity,
+    trade_delta,
+)
+
+__all__ = [
+    "MAX_GROSS_EXPOSURE",
+    "SCHEMA_VERSION",
+    "Action",
+    "AegisMetrics",
+    "Amend",
+    "Cancel",
+    "Context",
+    "Fanout",
+    "Fetch",
+    "InvalidSignal",
+    "LadderConfig",
+    "Metric",
+    "MetricSink",
+    "OverDelivery",
+    "Place",
+    "Placement",
+    "Resting",
+    "Signal",
+    "SignalSource",
+    "TouchLadder",
+    "UnknownOrder",
+    "check_intent",
+    "committed_change",
+    "parse_signal",
+    "round_price",
+    "round_quantity",
+    "target_quantity",
+    "trade_delta",
+    "validate",
+]

nyrobrain-0.1.0/src/nyrobrain/execution/aegis.py

@@ -0,0 +1,92 @@
+"""Publishing metrics to Aegis over the JetStream sidecar.
+
+Requires the ``aegis`` extra, which carries the gRPC client. The payloads — and
+every decision about what they contain — live in `nyrobrain.execution.metrics`,
+which needs nothing installed at all. A second transport replaces this file and
+inherits the rest.
+
+**This is not a NATS client.** `bq-nats-client` depends only on `grpcio` and
+`protobuf`: publishers reach JetStream through a sidecar authenticated by an API
+key and hold no NATS credentials. That is convenient here, and it is also why
+portfolio targets deliberately live in a different account — the sidecar applies
+no per-subject authorization, so anything publishable through it is publishable
+by any holder of a key.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Protocol
+
+from nyrobrain.execution.metrics import Metric
+
+
+class JetStreamClient(Protocol):
+    """The part of `nats_client.NATSClient` this uses.
+
+    Stated as a protocol so a test can drive the real sink without a sidecar,
+    and so the dependency is visible at a glance rather than implied by an
+    import.
+    """
+
+    async def jetstream(self) -> None: ...
+
+    async def js_publish(
+        self,
+        subject: str,
+        payload: bytes = b"",
+        headers: dict[str, str] | None = None,
+    ) -> object: ...
+
+
+class JetStreamSink:
+    """A `MetricSink` that publishes through the sidecar.
+
+    Deliberately thin, and deliberately not defensive: a publish that fails
+    raises. The emitter counts the failure and the report shows it, so a sink
+    that swallowed exceptions would turn a dead metrics pipeline into one that
+    looks healthy — the exact failure this map exists to prevent, and the one
+    nothing downstream detects.
+    """
+
+    def __init__(self, *, open_client: Callable[[], JetStreamClient]) -> None:
+        #: A factory, not a client, and that is the whole point. `NATSClient`
+        #: binds its gRPC channel to an event loop when it is **constructed**,
+        #: and a driver builds its publisher before the node has a loop — so a
+        #: ready-made client binds to a loop that is closed by the time the
+        #: first heartbeat fires, and every publish dies with "attached to a
+        #: different loop". Deferring construction to the first publish means
+        #: the channel is built in whichever loop is actually going to use it.
+        #:
+        #: Measured the hard way: a live run reported `published 0, failures 3`
+        #: and nothing else until the round started recording the reason.
+        self._open_client = open_client
+        self._client: JetStreamClient | None = None
+
+    async def connect(self) -> None:
+        """Build the client and configure JetStream, once.
+
+        Call this only from the loop that will publish — or not at all, since
+        `publish` does it. `js_publish` refuses with "call jetstream() first"
+        until it has run, and doing it per publish would add a round trip to
+        every row.
+        """
+        if self._client is not None:
+            return
+        client = self._open_client()
+        await client.jetstream()
+        self._client = client
+
+    async def publish(self, metric: Metric) -> None:
+        # Lazily, so the channel is built in whichever loop is publishing.
+        await self.connect()
+        assert self._client is not None
+        # `msg_id` becomes `Nats-Msg-Id` here and nowhere else. The client does
+        # `headers.setdefault("Nats-Msg-Id", uuid4())`, so omitting it would
+        # publish successfully while silently losing every cross-publish
+        # collapse — retries would still be idempotent, and nothing else would.
+        await self._client.js_publish(
+            metric.subject,
+            metric.payload,
+            headers={"Nats-Msg-Id": metric.msg_id},
+        )