spatialdds-ros 0.3.0__py3-none-any.whl

spatialdds_ros/frames.py

@@ -0,0 +1,219 @@
+"""
+Frames, and the one piece of arithmetic that fails silently.
+
+Two things live here: the `FrameRef` the robot stamps on every pose, and the
+`FrameTransform` that says where that frame sits on the earth — published only
+when an anchor is configured.
+
+**The direction of the transform is the thing to get right.** `parent_ref` is
+the *global* frame and `child_ref` the *local* one, with `T_parent_child`
+mapping parent into child. An inverted transform still produces a well-formed
+pose with plausible-looking numbers and places everything near the centre of
+the earth: no exception, no malformed record, nothing a schema check would
+catch. The prototype's `venue_georeference` carries the same warning, and for
+the same reason — the 1.7 announce spells the two ends `from` and `to` with
+`from` being the *local* frame, so anyone mapping by name rather than by role
+inverts it.
+
+The ENU↔ECEF projection is written once, here. Two copies would make a drift
+between consumers look like a disagreement about where the venue is.
+"""
+from __future__ import annotations
+
+import math
+import time
+import uuid
+from typing import Optional, Tuple
+
+from spatialdds_idl18.builtin import Time
+from spatialdds_idl18.spatial.common import (
+    CoordConvention, FrameRef, ScaleStatus)
+from spatialdds_idl18.spatial.core import CovMatrix, FrameTransform, PoseSE3
+
+from spatialdds_ros.config import Anchor
+from spatialdds_ros.topics import EARTH_FIXED_FQN
+
+
+def now_time() -> Time:
+    now = time.time()
+    return Time(sec=int(now), nanosec=int((now % 1) * 1e9))
+
+
+def frame_uuid(fqn: str) -> str:
+    """
+    A frame's uuid, derived from its name.
+
+    UUIDv5 of the fqn, which is how every other participant in this family
+    derives it. Load-bearing rather than tidy: the scene, a catalogue and an
+    announce all naming the same frame must produce the same uuid, or they
+    describe three frames that happen to share a name.
+    """
+    return str(uuid.uuid5(uuid.NAMESPACE_URL, fqn))
+
+
+def robot_frame(fqn: str) -> FrameRef:
+    """
+    The frame the robot's pose is expressed in.
+
+    **The scale quartet is filled, and it is the one number this library
+    asserts without measuring it.** REP-103 makes ROS metric, so
+    `SCALE_DECLARED` with `meters_per_unit = 1.0` is a true statement about any
+    conformant ROS robot rather than a guess — and `SCALE_DECLARED` rather than
+    `SCALE_DERIVED` because nobody recovered it from a similarity transform;
+    the units were metres to begin with.
+
+    `has_scale = false` would also mean metric — the spec makes every pre-1.8
+    publisher correct by construction — so these four members change nothing a
+    consumer computes. They change what it has to assume. They are also
+    exactly the four a 1.7 reader truncates away, which is the era boundary
+    working as designed rather than a fault.
+    """
+    return FrameRef(
+        uuid=frame_uuid(fqn),
+        fqn=fqn,
+        has_coord_convention=True,
+        coord_convention=CoordConvention.ENU,
+        has_scale=True,
+        scale_status=ScaleStatus.SCALE_DECLARED,
+        meters_per_unit=1.0,
+        display_unit="m",
+    )
+
+
+def earth_fixed_frame() -> FrameRef:
+    """
+    The global frame a georeference is relative to.
+
+    No coordinate convention: ECEF is not one of the conventions
+    `CoordConvention` can name, so claiming one would be false. Saying nothing
+    is the accurate answer, and `has_coord_convention = False` is how the type
+    says it.
+    """
+    return FrameRef(
+        uuid=frame_uuid(EARTH_FIXED_FQN),
+        fqn=EARTH_FIXED_FQN,
+        has_coord_convention=False,
+        coord_convention=CoordConvention.ENU,     # unread while the flag is off
+        has_scale=True,
+        scale_status=ScaleStatus.SCALE_DECLARED,
+        meters_per_unit=1.0,
+        display_unit="m",
+    )
+
+
+def enu_to_ecef_pose(lat_deg: float, lon_deg: float,
+                     height_m: float) -> Tuple[list, list]:
+    """
+    A local ENU frame's origin and basis, in earth-fixed metres.
+
+    Returns ``(t, q)``: the translation is the frame origin's ECEF position and
+    the quaternion (x, y, z, w) is the ENU basis at that origin, so the pose
+    maps **from** the local frame **into** earth-fixed.
+
+    WGS84. One implementation, because a difference between two consumers
+    should come from their anchors and never from two copies of this drifting
+    apart.
+    """
+    lat, lon = math.radians(lat_deg), math.radians(lon_deg)
+    a, f = 6378137.0, 1.0 / 298.257223563
+    e2 = f * (2.0 - f)
+    n = a / math.sqrt(1.0 - e2 * math.sin(lat) ** 2)
+    t = [(n + height_m) * math.cos(lat) * math.cos(lon),
+         (n + height_m) * math.cos(lat) * math.sin(lon),
+         (n * (1.0 - e2) + height_m) * math.sin(lat)]
+
+    # The ENU basis at (lat, lon), as columns: east, north, up.
+    sl, cl = math.sin(lon), math.cos(lon)
+    sp, cp = math.sin(lat), math.cos(lat)
+    east = (-sl, cl, 0.0)
+    north = (-sp * cl, -sp * sl, cp)
+    up = (cp * cl, cp * sl, sp)
+    m = ((east[0], north[0], up[0]),
+         (east[1], north[1], up[1]),
+         (east[2], north[2], up[2]))
+
+    # Matrix to quaternion, branching on the trace for numerical conditioning.
+    trace = m[0][0] + m[1][1] + m[2][2]
+    if trace > 0.0:
+        s = math.sqrt(trace + 1.0) * 2.0
+        w = 0.25 * s
+        x = (m[2][1] - m[1][2]) / s
+        y = (m[0][2] - m[2][0]) / s
+        z = (m[1][0] - m[0][1]) / s
+    elif m[0][0] > m[1][1] and m[0][0] > m[2][2]:
+        s = math.sqrt(1.0 + m[0][0] - m[1][1] - m[2][2]) * 2.0
+        w = (m[2][1] - m[1][2]) / s
+        x = 0.25 * s
+        y = (m[0][1] + m[1][0]) / s
+        z = (m[0][2] + m[2][0]) / s
+    elif m[1][1] > m[2][2]:
+        s = math.sqrt(1.0 + m[1][1] - m[0][0] - m[2][2]) * 2.0
+        w = (m[0][2] - m[2][0]) / s
+        x = (m[0][1] + m[1][0]) / s
+        y = 0.25 * s
+        z = (m[1][2] + m[2][1]) / s
+    else:
+        s = math.sqrt(1.0 + m[2][2] - m[0][0] - m[1][1]) * 2.0
+        w = (m[1][0] - m[0][1]) / s
+        x = (m[0][2] + m[2][0]) / s
+        y = (m[1][2] + m[2][1]) / s
+        z = 0.25 * s
+    return t, [x, y, z, w]
+
+
+def georeference(frame_id: str, anchor: Anchor) -> FrameTransform:
+    """
+    Where `frame_id`'s origin sits on the earth — the robot's own claim.
+
+    Published only when an anchor is configured; `Config.publishes_georeference`
+    is the gate, and its absence is a documented mode rather than a failure.
+
+    **Direction, stated at the construction site because this is where it goes
+    wrong.** `parent_ref` is earth-fixed, the global frame. `child_ref` is the
+    local frame. Following the 1.7 announce's `from`/`to` spelling instead
+    would invert it and place the frame near the centre of the earth with every
+    number still looking plausible.
+
+    `cov` is a union and has to say which arm it is using. `COV_NONE` is the
+    honest answer for an anchor somebody typed into a launch file: there are no
+    error bars on it, and there is no implicit absent value to leave it at.
+    """
+    t, q = enu_to_ecef_pose(anchor.lat_deg, anchor.lon_deg, anchor.height_m)
+    return FrameTransform(
+        transform_id=f"xf:{frame_uuid(frame_id)}",
+        parent_ref=earth_fixed_frame(),
+        child_ref=robot_frame(frame_id),
+        T_parent_child=PoseSE3(t=t, q=q),
+        stamp=now_time(),
+        cov=CovMatrix(none=0),
+    )
+
+
+def yaw_quaternion(yaw: float) -> list:
+    """A rotation about the frame's up axis, as (x, y, z, w)."""
+    return [0.0, 0.0, math.sin(yaw / 2.0), math.cos(yaw / 2.0)]
+
+
+def pose_at(x: float, y: float, z: float, yaw: float) -> PoseSE3:
+    return PoseSE3(t=[x, y, z], q=yaw_quaternion(yaw))
+
+
+def geodetic_of(t) -> Tuple[float, float, float]:
+    """
+    ECEF metres back to (lat, lon, height). The inverse of the translation
+    above, provided so a test can compose the two and check the round trip —
+    an inverted or mis-scaled transform is caught by composing it, not by
+    reading it.
+    """
+    x, y, z = t[0], t[1], t[2]
+    a, f = 6378137.0, 1.0 / 298.257223563
+    e2 = f * (2.0 - f)
+    lon = math.atan2(y, x)
+    p = math.hypot(x, y)
+    lat = math.atan2(z, p)
+    for _ in range(8):
+        n = a / math.sqrt(1.0 - e2 * math.sin(lat) ** 2)
+        h = p / math.cos(lat) - n
+        lat = math.atan2(z, p * (1.0 - e2 * n / (n + h)))
+    n = a / math.sqrt(1.0 - e2 * math.sin(lat) ** 2)
+    return math.degrees(lat), math.degrees(lon), p / math.cos(lat) - n

spatialdds_ros/kinematic.py

@@ -0,0 +1,140 @@
+"""
+The no-hardware mode: a robot that drives in straight lines.
+
+This is the library's CI story and its try-it story, the same role the
+prototype's `PlazaSim` played. It exists so the whole chain — entity on the
+bus, a command accepted, a refusal reaching the asker — can be exercised with
+no ROS, no nav2 and no robot.
+
+**What it deliberately does not carry.** The prototype's sim tested every step
+against a mask built from the venue's declared extents, and refused to enter.
+That coupling does not travel: for a real robot the clearance is nav2's
+footprint and inflation radius, which nav2 already owns, and the prototype's
+own clearance constant is documented as tied to a GLB scaled up for on-screen
+legibility rather than to a robot. The census rules the keep-out job as the
+costmap-filter path, and this source is not it.
+
+**What it carries instead, and why.** Optional `bounds`: an axis-aligned box
+this sim will not leave. Default unbounded, so by default nothing is refused.
+Bounds are not a world model and make no claim about a venue — they are a
+property of the sim, the way a treadmill is a property of a test rig. They are
+here because the *shape* of a real late refusal needs reproducing: whether a
+goal is drivable depends on where the robot is when it meets the boundary, so
+the refusal necessarily arrives after the acceptance. A source that could only
+accept would leave that path unexercised in the one mode anybody can run
+without hardware.
+"""
+from __future__ import annotations
+
+import math
+from typing import Optional, Tuple
+
+#: Metres per second. Fast enough that a test does not wait, slow enough that
+#: a person watching can see it move.
+DEFAULT_SPEED_MPS = 0.6
+
+#: How close counts as arrived.
+ARRIVAL_M = 0.05
+
+
+class Bounds:
+    """An axis-aligned box the sim will not leave."""
+
+    def __init__(self, min_x: float, min_y: float,
+                 max_x: float, max_y: float) -> None:
+        if min_x >= max_x or min_y >= max_y:
+            raise ValueError(
+                f"bounds are empty: x [{min_x}, {max_x}], y [{min_y}, {max_y}]")
+        self.min_x, self.min_y = min_x, min_y
+        self.max_x, self.max_y = max_x, max_y
+
+    def contains(self, x: float, y: float) -> bool:
+        return (self.min_x <= x <= self.max_x
+                and self.min_y <= y <= self.max_y)
+
+    def __repr__(self) -> str:                                # pragma: no cover
+        return (f"Bounds(x [{self.min_x}, {self.max_x}], "
+                f"y [{self.min_y}, {self.max_y}])")
+
+
+class KinematicSource:
+    """
+    A pose that walks towards a goal in a straight line.
+
+    No physics, no sensors, no world model. `step` returns the new pose; when
+    it has had to give up on a goal it sets `abandoned` to the reason, which
+    the caller is expected to pass to `RobotAdapter.refused` so whoever asked
+    finds out.
+    """
+
+    def __init__(self, start: Tuple[float, float] = (0.0, 0.0),
+                 yaw: float = 0.0, speed: float = DEFAULT_SPEED_MPS,
+                 bounds: Optional[Bounds] = None) -> None:
+        self.x, self.y = start
+        self.yaw = yaw
+        self.speed = speed
+        self.bounds = bounds
+        self.goal: Optional[Tuple[float, float]] = None
+        #: Set when a goal was dropped, cleared by the caller once reported.
+        self.abandoned: Optional[str] = None
+        if bounds is not None and not bounds.contains(self.x, self.y):
+            raise ValueError(
+                f"the start position ({self.x}, {self.y}) is outside the "
+                f"configured bounds, so this sim would be refusing from its "
+                f"first step")
+
+    def step(self, dt: float) -> Tuple[float, float, float]:
+        """Advance by `dt` seconds. Returns (x, y, yaw)."""
+        if self.goal is None:
+            # Idle is *still*. A sim that drifted while idle would publish
+            # motion nobody asked for, and the fast lane would carry it.
+            return self.x, self.y, self.yaw
+
+        gx, gy = self.goal
+        dx, dy = gx - self.x, gy - self.y
+        distance = math.hypot(dx, dy)
+        if distance <= ARRIVAL_M:
+            self.x, self.y, self.goal = gx, gy, None
+            return self.x, self.y, self.yaw
+
+        yaw = math.atan2(dy, dx)
+        step = min(self.speed * dt, distance)
+        x = self.x + step * math.cos(yaw)
+        y = self.y + step * math.sin(yaw)
+
+        if self.bounds is not None and not self.bounds.contains(x, y):
+            # **The reason cannot be known at accept time**, which is the whole
+            # point of this branch: it depends on where the robot is when it
+            # meets the boundary. So the goal was honestly accepted and is
+            # honestly given up on here, with a reason the asker can read.
+            self.abandoned = (
+                f"goal ({gx:.2f}, {gy:.2f}) abandoned at "
+                f"({self.x:.2f}, {self.y:.2f}) — a straight line from here "
+                f"leaves this source's configured bounds, and it drives "
+                f"straight lines only rather than planning around them. Send "
+                f"a waypoint inside the bounds, or run a real planner")
+            self.goal = None
+            return self.x, self.y, self.yaw
+
+        self.yaw, self.x, self.y = yaw, x, y
+        return self.x, self.y, self.yaw
+
+
+class KinematicNavigator:
+    """
+    `RobotAdapter`'s navigator, backed by the sim above.
+
+    `available()` is always `None`: there is nothing for a straight-line sim to
+    be unavailable for, and claiming otherwise would make the adapter decline
+    goals it can in fact take.
+    """
+
+    def __init__(self, source: KinematicSource) -> None:
+        self._source = source
+
+    def available(self) -> Optional[str]:
+        return None
+
+    def send(self, x: float, y: float) -> str:
+        self._source.goal = (x, y)
+        return f"the kinematic source is heading for ({x:.2f}, {y:.2f})"

spatialdds_ros/qos.py

@@ -0,0 +1,101 @@
+"""
+The three QoS profiles this library's lanes use, from spec §3.3.3.
+
+**Not configurable, and this is the clearest case in the library.** QoS in DDS
+is a request/offered contract: endpoints match only when the reader's request
+is compatible with the writer's offer, and when they do not match *nothing
+happens*. No error, no warning, no mismatch reported — the reader simply never
+receives, which is indistinguishable from a writer that is not publishing.
+
+The prototype has the scar. Deadline is one of those request/offered policies,
+so a reader requesting 33 ms does not match a writer offering none. An
+independently-built probe transcribed the spec's older table, read its
+"Typical" column heading as advisory, omitted the deadlines, and exchanged
+nothing at all; `tests/test_interop.py::DeadlineIsLoadBearing` in
+SpatialDDS-demo pins the behaviour. A dash in the spec's deadline column means
+*no deadline*, which is a different statement from an unstated one.
+
+So a QoS knob on this library would be a way for an operator to build a robot
+that is invisible to the scene, with nothing anywhere saying why. There is one
+right answer per lane and the library fills it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+try:                                    # pragma: no cover - import shape
+    from cyclonedds import qos as _qos, util as _util
+    HAVE_CYCLONEDDS = True
+except Exception:                       # pragma: no cover - import shape
+    # Importable without CycloneDDS so the profile *table* can be read and
+    # asserted on a machine with no DDS build — which is where this library's
+    # unit tests run. `to_qos` is the only thing that needs the binding.
+    _qos = _util = None                                     # type: ignore
+    HAVE_CYCLONEDDS = False
+
+
+@dataclass(frozen=True)
+class QosProfile:
+    """One row of §3.3.3, transcribed field for field."""
+
+    name: str
+    reliable: bool
+    deadline_ms: Optional[int]
+    latched: bool = False
+    keep_last: Optional[int] = None          # None means KEEP_ALL
+    note: str = ""
+
+    def to_qos(self, lifespan_sec: Optional[float] = None):
+        """This row as a CycloneDDS `Qos`."""
+        if not HAVE_CYCLONEDDS:             # pragma: no cover - import shape
+            raise RuntimeError(
+                "cyclonedds is not importable, so no QoS can be built. The "
+                "profile table itself is readable without it")
+        policies = [
+            _qos.Policy.Reliability.Reliable(_util.duration(seconds=1))
+            if self.reliable else _qos.Policy.Reliability.BestEffort,
+            _qos.Policy.Durability.TransientLocal if self.latched
+            else _qos.Policy.Durability.Volatile,
+            _qos.Policy.History.KeepLast(self.keep_last) if self.keep_last
+            else _qos.Policy.History.KeepAll,
+        ]
+        if self.deadline_ms is not None:
+            policies.append(
+                _qos.Policy.Deadline(
+                    _util.duration(milliseconds=self.deadline_ms)))
+        if lifespan_sec:
+            # A payload TTL (an announce's `ttl_sec`) mapped onto DDS Lifespan,
+            # so the middleware expires a stale sample rather than every
+            # consumer re-deriving staleness.
+            policies.append(
+                _qos.Policy.Lifespan(_util.duration(seconds=lifespan_sec)))
+        return _qos.Qos(*policies)
+
+
+#: What exists and what it is. TRANSIENT_LOCAL so a client that connects after
+#: the robot has been running still learns the robot is there — the property
+#: the whole model layer rests on, and the reason a late joiner needs no query.
+MODEL_LATCHED = QosProfile(
+    "MODEL_LATCHED", reliable=True, deadline_ms=None, latched=True,
+    keep_last=1,
+    note="RELIABLE + TRANSIENT_LOCAL + KEEP_LAST(1) per key",
+)
+
+#: Where it is now. BEST_EFFORT because a pose that missed its moment is worth
+#: less than the next one; VOLATILE because a late joiner should read the
+#: latched record rather than a pose from before it existed.
+MODEL_FAST = QosProfile(
+    "MODEL_FAST", reliable=False, deadline_ms=None, latched=False, keep_last=1,
+    note="BEST_EFFORT + VOLATILE + KEEP_LAST(1) per key -- the tempo lane",
+)
+
+#: Requests. RELIABLE so one is not lost in transit, VOLATILE so a restarting
+#: participant does not replay yesterday's goals at a robot that has moved.
+MODEL_COMMAND = QosProfile(
+    "MODEL_COMMAND", reliable=True, deadline_ms=None, latched=False,
+    keep_last=16,
+    note="RELIABLE + VOLATILE + KEEP_LAST(16), unkeyed -- a request, not a claim",
+)
+
+PROFILES = {p.name: p for p in (MODEL_LATCHED, MODEL_FAST, MODEL_COMMAND)}

spatialdds_ros/recording.py

@@ -0,0 +1,167 @@
+"""
+Record this library's lanes to a typed SpatialDDS MCAP.
+
+The file this writes is the one `spatialdds serve --mcap` reads — the
+unmodified gateway from PyPI, with no adapter in between. That is the point:
+if the gateway can serve it, the bytes on the bus were conformant, and the
+check is the gateway rather than an assertion of mine.
+
+**The format is defined by what the gateway reads, not chosen here.** Matching
+the packaged `fountain-anchors.mcap`: one schema per type, named in *colon*
+form (`spatial::owm::Entity`), `encoding="omgidl"`, data being the flattened
+IDL text; one channel per topic with `message_encoding="cdr"`; and each
+message the sample's own CycloneDDS serialization.
+
+That last part is worth stating because it is the load-bearing coincidence,
+and it was verified rather than assumed: `Entity.serialize()` from
+cyclonedds-python decodes with `spatialdds.server.xcdr2.Decoder` against the
+model built from this IDL, 1.8's appended scale members included. Nothing
+re-encodes anything — the bytes recorded are the bytes that were on the wire.
+
+Note the contrast with the prototype's `bridges/mcap_bridge`, which writes
+`message_encoding="json"` with `encoding="jsonschema"`. That is a 1.7 lane for
+a different consumer and is not what the gateway reads; a recording in that
+format would be a perfectly good MCAP that `serve --mcap` could not use.
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from spatialdds_idl18.spatial.core import FrameTransform
+from spatialdds_idl18.spatial.disco import Announce
+from spatialdds_idl18.spatial.owm import Entity, ModelCommand, ModelPose
+
+from spatialdds_ros.announce import ANNOUNCE_TOPIC
+from spatialdds_ros.config import Config
+from spatialdds_ros.topics import Topics
+
+#: The IDL closure the four model types need, relative to `idl/v1.8`.
+#: `provisional/owm.idl` is here because `spatial.owm` is provisional and
+#: independently versioned, so the `spatialdds` package does not vendor it —
+#: and should not. This repository does.
+CLOSURE = ["types.idl", "core.idl", "provisional/owm.idl"]
+
+#: And the closure for the discovery lane, which `Announce` needs.
+DISCOVERY_CLOSURE = ["types.idl", "core.idl", "discovery.idl"]
+
+#: Where the vendored IDL lives, and where it came from. Kept beside the
+#: generated bindings' provenance deliberately: a recording whose schemas came
+#: from a different spec revision than the bindings that produced the bytes
+#: would be two type systems in one file.
+IDL_DIR = Path(__file__).resolve().parent.parent / "idl" / "v1.8"
+SPEC_COMMIT = "9c3e1f2"
+
+
+def lanes(config: Config) -> Dict[str, tuple]:
+    """
+    Topic -> (python class, colon fqn, dotted fqn, closure).
+
+    The four model lanes plus discovery. Discovery is not scene-scoped — it is
+    the one place a participant looks before it knows what scenes exist.
+    """
+    names = Topics(config.scene)
+    return {
+        names.entity: (Entity, "spatial::owm::Entity",
+                       "spatial.owm.Entity", CLOSURE),
+        names.pose: (ModelPose, "spatial::owm::ModelPose",
+                     "spatial.owm.ModelPose", CLOSURE),
+        names.command: (ModelCommand, "spatial::owm::ModelCommand",
+                        "spatial.owm.ModelCommand", CLOSURE),
+        names.frame_transform: (FrameTransform,
+                                "spatial::core::FrameTransform",
+                                "spatial.core.FrameTransform", CLOSURE),
+        ANNOUNCE_TOPIC: (Announce, "spatial::disco::Announce",
+                         "spatial.disco.Announce", DISCOVERY_CLOSURE),
+    }
+
+
+class Recorder:
+    """
+    One MCAP writer, schemas and channels registered on first sight.
+
+    Lazily, because a lane with nothing on it should not appear in the
+    recording: an empty channel tells a reader a lane exists and said nothing,
+    which is a claim this recorder is not in a position to make — it only knows
+    what it saw.
+    """
+
+    def __init__(self, path: Path, config: Config) -> None:
+        from mcap.writer import Writer
+
+        self.path = Path(path)
+        self.config = config
+        self._lanes = lanes(config)
+        self._handle = self.path.open("wb")
+        self._writer = Writer(self._handle)
+        self._writer.start()
+        self._schema_ids: Dict[str, int] = {}
+        self._channel_ids: Dict[str, int] = {}
+        self._flat: Dict[str, bytes] = {}
+        self.counts: Dict[str, int] = {}
+
+    # --- schemas and channels --------------------------------------------
+
+    def _flattened(self, closure_key: str, closure: list) -> bytes:
+        if closure_key not in self._flat:
+            from spatialdds.server import pin
+            self._flat[closure_key] = pin.flatten(IDL_DIR, closure).encode()
+        return self._flat[closure_key]
+
+    def _schema_id(self, colon_fqn: str, closure: list) -> int:
+        if colon_fqn not in self._schema_ids:
+            closure_key = ",".join(closure)
+            self._schema_ids[colon_fqn] = self._writer.register_schema(
+                name=colon_fqn, encoding="omgidl",
+                data=self._flattened(closure_key, closure))
+        return self._schema_ids[colon_fqn]
+
+    def _channel_id(self, topic: str) -> int:
+        if topic not in self._channel_ids:
+            _cls, colon_fqn, dotted, closure = self._lanes[topic]
+            self._channel_ids[topic] = self._writer.register_channel(
+                schema_id=self._schema_id(colon_fqn, closure),
+                topic=topic,
+                message_encoding="cdr",
+                metadata={
+                    "spatialdds_type": dotted,
+                    "spatialdds_version": "1.8",
+                    "spatialdds_idl": f"SpatialDDS-spec {SPEC_COMMIT}",
+                })
+            self.counts.setdefault(topic, 0)
+        return self._channel_ids[topic]
+
+    # --- writing ----------------------------------------------------------
+
+    def write(self, topic: str, sample: Any,
+              log_time_ns: Optional[int] = None) -> None:
+        """
+        One sample, as the bytes it was on the wire.
+
+        `sample.serialize()` and nothing else: re-encoding would make this a
+        recording of what the recorder thinks the sample means rather than of
+        what was published.
+        """
+        if topic not in self._lanes:
+            raise KeyError(
+                f"{topic!r} is not a lane this recorder knows; expected one of "
+                f"{sorted(self._lanes)}")
+        now = time.time_ns() if log_time_ns is None else log_time_ns
+        self._writer.add_message(
+            channel_id=self._channel_id(topic),
+            log_time=now, publish_time=now, data=sample.serialize())
+        self.counts[topic] = self.counts.get(topic, 0) + 1
+
+    def close(self) -> Dict[str, int]:
+        """Finish the file and return what was recorded, per lane."""
+        self._writer.finish()
+        self._handle.close()
+        return dict(self.counts)
+
+    def __enter__(self) -> "Recorder":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        if not self._handle.closed:
+            self.close()