transform-tree 0.0.2__cp39-abi3-win_amd64.whl

tf_tree/__init__.py

@@ -0,0 +1,107 @@
+"""tf_tree — a transform tree engine.
+
+A faster, more scalable alternative to ROS ``tf2``.
+
+Two things surprise people, and both are deliberate:
+
+**Stamps are integer nanoseconds.** There is no float-seconds overload. At a
+2026 epoch the ULP of ``float64`` seconds is 238 ns, so *every* interval in a
+1 kHz stream is wrong after a round trip. :func:`from_sec` exists for callers
+who genuinely have float seconds and accept the loss.
+
+**Nothing returns a view into shared memory.** An edge's samples are a ring
+being overwritten by another process, and correct reads go through a seqlock;
+an array pointing into it would be a data race by construction. "Zero-copy"
+here means no *intermediate* allocation — results are written once, into their
+final home. Use :meth:`Plan.at_into` to supply that home yourself.
+
+**Identifying a build.** A benchmark number or a bug report has to say which
+build produced it, and three values do that::
+
+    tf_tree.__version__                     # the extension build, as a str
+    tf_tree.arena_format_version()          # the header's set of fields
+    f"0x{tf_tree.arena_layout_hash():08X}"  # the geometry, as tft prints it
+
+They are three because they fail independently: the right version can still
+refuse to attach, because the arena it was pointed at was written by a
+different geometry. The last two are what every participant compares on attach.
+
+``__version__`` is compiled in from ``crates/tf_tree_py/Cargo.toml``, and it is
+*not* the canonical answer for the wheel: ``importlib.metadata.version`` is,
+and it reads ``pyproject.toml``. ``tests/python/test_version.py`` asserts the
+two agree, so a disagreement is a stale wheel or a half-applied bump rather
+than two right answers — which is the attribution this whole trio exists to
+get right.
+"""
+
+from ._core import (
+    BufferError,
+    DerivativesUnavailableError,
+    DisconnectedError,
+    ExtrapolationError,
+    FrameNotDeclaredError,
+    NoDataError,
+    NoSegmentError,
+    Plan,
+    Publisher,
+    TfTreeError,
+    TopologyChangedError,
+    Tree,
+    arena_format_version,
+    arena_layout_hash,
+    build,
+    from_parts,
+    from_ros,
+    from_sec,
+    has_shared_memory,
+    open_arena,
+    open_file,
+    push,
+)
+
+# Its own statement, and the redundant alias is not a typo. `__version__` is
+# deliberately absent from `__all__` (the note below it says why), so the alias
+# is what marks it as re-exported — without it ruff reports F401 and a type
+# checker treats the name as private to this module. ruff's isort keeps aliased
+# imports in a separate statement from plain ones, which is why it is down here
+# rather than inside the block above.
+from ._core import (
+    __version__ as __version__,
+)
+
+__all__ = [
+    "BufferError",
+    "DerivativesUnavailableError",
+    "DisconnectedError",
+    "ExtrapolationError",
+    "FrameNotDeclaredError",
+    "NoDataError",
+    "NoSegmentError",
+    "Plan",
+    "Publisher",
+    "TfTreeError",
+    "TopologyChangedError",
+    "Tree",
+    "arena_format_version",
+    "arena_layout_hash",
+    "build",
+    "from_parts",
+    "from_ros",
+    "from_sec",
+    "has_shared_memory",
+    "open",
+    "open_arena",
+    "open_file",
+    "push",
+]
+
+# `__version__` is deliberately absent from `__all__` above. It is not an
+# oversight and not a style call: `tests/python/test_stubs.py` asserts `__all__`
+# equals the package's public namespace, and it computes that namespace by
+# skipping underscore-prefixed names — so listing the dunder here would make
+# those two sets differ by exactly this name. `from tf_tree import *` binding a
+# `__version__` is not something anyone wants either.
+
+# `open` shadows the builtin inside this module only; the public spelling is
+# `tf_tree.open()`, which is what §4.1 promises.
+open = open_arena  # noqa: A001

tf_tree/_core.pyi

@@ -0,0 +1,544 @@
+"""Type stubs for the `tf_tree` extension module.
+
+Hand-written, not generated (`docs/PHASE3.md` §9). Generated stubs cannot
+express the scalar-vs-array return overloads on `Plan.at`, and those overloads
+are the most important thing a user needs to see: they are what makes the
+vectorised path the obvious one.
+
+The standing hazard with hand-written stubs is not that they are wrong on day
+one — it is that a method added in Rust never reaches them. `tests/python/
+test_stubs.py` closes that: it asserts every public symbol of the built module
+appears here. Signatures are ours; *existence* is checkable, and that is the
+half that rots.
+"""
+
+import os
+from typing import Literal, overload
+
+import numpy as np
+from numpy.typing import NDArray
+
+class TfTreeError(Exception): ...
+class ExtrapolationError(TfTreeError): ...
+class DisconnectedError(TfTreeError): ...
+class NoDataError(TfTreeError): ...
+class TopologyChangedError(TfTreeError): ...
+class FrameNotDeclaredError(TfTreeError): ...
+class BufferError(TfTreeError): ...
+
+class DerivativesUnavailableError(TfTreeError):
+    """This edge's interpolator has no exact derivative.
+
+    Raised only by `layout="quat_twist"`: `LerpSlerp` is `tf2`'s interpolator
+    and has no exact body twist, so it is refused rather than
+    finite-differenced. Declare the edge `ScLerp` — which is the default — or
+    ask for a pose layout.
+
+    A property of the *edge*, so it fires at element 0 of a batch and does not
+    go away on its own. Its sibling `NoSegmentError` is the opposite.
+    """
+
+class NoSegmentError(TfTreeError):
+    """A pose exists at this stamp, but no segment to differentiate.
+
+    The other refusal `layout="quat_twist"` adds over the pose layouts, and the
+    one that is **transient**: the edge retains a single sample, or the two
+    samples bracketing the stamp carry equal stamps (which is legal — stamps are
+    non-decreasing, not strictly increasing). Publish another sample, or ask
+    again later.
+
+    Distinct from `NoDataError`, which means the edge is empty. Here the
+    transform is perfectly well defined and only the derivative is not, so being
+    told "no data" would send you to the wrong problem. A property of the
+    *stamp*, so it can fire partway through a batch.
+    """
+
+F32Layout = Literal["affine32"]
+"""The one layout that writes `float32`."""
+
+F64Layout = Literal["mat4", "quat", "quat_twist"]
+"""The layouts that write `float64`."""
+
+Layout = Literal["mat4", "quat", "affine32", "quat_twist"]
+"""How a transform is written into memory. Stated, never inferred.
+
+`"mat4"` is `(4, 4)` / `(N, 4, 4)` float64; `"quat"` is `(7,)` / `(N, 7)`
+float64 as `[qw qx qy qz tx ty tz]`; `"affine32"` is `(12,)` / `(N, 12)`
+**float32**, row-major 3x4, GPU-facing; `"quat_twist"` is `(13,)` / `(N, 13)`
+float64, `"quat"` with the body twist `[wx wy wz vx vy vz]` appended.
+"""
+
+class Plan:
+    """A compiled lookup path. Build with `Tree.plan`."""
+
+    @overload
+    def at(self, stamps: int, /) -> NDArray[np.float64]:
+        """One stamp in, one `(4, 4)` float64 transform out.
+
+        The default layout is `"mat4"`, which is float64 — so this returns
+        `NDArray[np.float64]`, not a union a caller has to narrow. Only
+        `layout="affine32"` produces float32, and it has its own overload.
+        """
+
+    @overload
+    def at(self, stamps: NDArray[np.int64], /) -> NDArray[np.float64]:
+        """`(N,)` stamps in, `(N, 4, 4)` float64 out — the path to prefer.
+
+        A Python loop over the scalar form costs ~200 ns per iteration; this
+        amortises to near-native.
+        """
+
+    @overload
+    def at(
+        self, stamps: int | NDArray[np.int64], /, *, layout: F32Layout
+    ) -> NDArray[np.float32]:
+        """`layout="affine32"`: `(12,)` or `(N, 12)` **float32**, row-major 3x4."""
+
+    @overload
+    def at(
+        self, stamps: int | NDArray[np.int64], /, *, layout: F64Layout | None = ...
+    ) -> NDArray[np.float64]:
+        """`layout=` selects what is written per stamp (see `Layout`).
+
+        Keyword-only; `stamps` stays positional-only, which is where the
+        measured 29 ns of `METH_FASTCALL` lives.
+
+        `layout="quat_twist"` is `at_with_derivatives` as a batch: it appends
+        the body twist, in the plan's **source** frame, angular part first. It
+        is the only layout that can raise `DerivativesUnavailableError` or
+        `NoSegmentError`.
+        """
+
+    @overload
+    def at(
+        self, stamps: int | NDArray[np.int64], /, *, layout: Layout | None = ...
+    ) -> NDArray[np.float64] | NDArray[np.float32]:
+        """The fallback, for a `layout` whose value is not statically known.
+
+        Passing a variable of type `Layout` cannot resolve to one dtype, so this
+        is the only overload that hands back a union — and it is reached only by
+        a caller who genuinely does not know which layout they are asking for.
+        """
+
+    @overload
+    def at_into(
+        self, stamps: int, out: object, /, *, layout: Layout | None = ...
+    ) -> None:
+        """Evaluate one stamp into a caller-provided `(4, 4)` float64 array.
+
+        **The allocation-free scalar path, for a control loop.** A node does one
+        lookup per tick and cannot batch, so `at`'s per-call array allocation is
+        paid every tick forever. Measured on a depth-3 chain, release build:
+        `at` 224 ns against `at_into` **173 ns**, and nothing allocated.
+
+        Allocate `out` once, outside the loop.
+        """
+
+    @overload
+    def at_into(
+        self, stamps: NDArray[np.int64], out: object, /, *, layout: Layout | None = ...
+    ) -> None:
+        """Evaluate into a caller-provided `(N, 4, 4)` float64 array.
+
+        With `layout=`, `out` is `(N, layout_elems)` — or `(layout_elems,)` for
+        a scalar stamp — and `float32` for `"affine32"`, `float64` otherwise.
+        Every batch entry point has an `_into` form (`API.md` R2), so a layout
+        reachable only through the allocating call would be a batch path with
+        no allocation-free tier.
+
+        Allocates nothing. `out` must be C-contiguous and exactly the right
+        shape; it is validated completely *before* any element is written, so a
+        rejected call leaves it untouched.
+
+        Raises `BufferError` on a wrong shape, dtype or stride. Non-contiguous
+        input is refused rather than silently copied — a silent copy would
+        defeat the point of this method while appearing to work.
+
+        **With `layout=`, a bad `stamps` is reported the way `at` reports it**
+        — numpy's or PyO3's own conversion `TypeError` ("only integer scalar
+        arrays can be converted to a scalar index" for a float64 array) rather
+        than a `BufferError` naming `(N,) int64`. That is the trade for the two
+        things it bought: an `np.int64` scalar is accepted, and a `float` stamp
+        meets the `TypeError` carrying the 238 ns measurement instead of a
+        complaint about a buffer. The default `mat4` path still gives the
+        shape-naming `BufferError`, and still refuses `np.int64`; the
+        difference is in `Plan.at_into.__doc__`.
+
+        `out` is typed `object` rather than `NDArray` because the device check
+        below accepts anything and then refuses it by message. **Only
+        `numpy.ndarray` is written to** (subclasses included); a `memoryview`,
+        or a pinned torch or CuPy allocation, is refused whatever its layout.
+        `PHASE3.md` §5.5 describes those as qualifying and that is **not
+        implemented** — `np.asarray(...)` first.
+
+        **Device memory is refused** with a message naming the fix: a CPU store
+        to a `cudaMalloc` pointer is undefined, not slow.
+
+        A genuine `numpy.ndarray` skips the device check, because its data
+        pointer is host memory by construction; CuPy and torch arrays are not
+        numpy subclasses, so they still pay for it. The probe is a Python method
+        call — `__dlpack_device__()` — and running it on every numpy call cost
+        ~120 ns of a ~173 ns lookup.
+        """
+
+    def adaptive(
+        self,
+        start_ns: int,
+        end_ns: int,
+        /,
+        *,
+        lin: float = ...,
+        ang: float = ...,
+    ) -> tuple[NDArray[np.int64], NDArray[np.float64]]:
+        """Knots whose linear interpolation stays within `lin` m / `ang` rad.
+
+        Returns `(stamps, poses)` of shapes `(K,)` and `(K, 4, 4)`, strictly
+        increasing. LERP between adjacent knots on whatever device they live
+        on; the reconstruction error is bounded by construction.
+        """
+
+    def latest(self) -> NDArray[np.float64]:
+        """The most recent transform on this path, as `(4, 4)`."""
+
+    def depth(self) -> int:
+        """Folded depth of this path, in edges."""
+
+    def edges(self) -> list[tuple[str, str]]:
+        """The **dynamic** edges this plan samples, as `(parent, child)` pairs.
+
+        In fold order — the order the compositions happen, which is the order
+        the plan is.
+
+        Shorter than `depth()` when the path crosses a static edge. A static
+        edge (or a whole run of them) is folded into one constant transform at
+        compile time and its identity does not survive the fold, so a plan
+        cannot list what it no longer knows. Use `Tree.edges()` for the
+        topology; this is what *this path samples at evaluation time*.
+
+        Raises `TfTreeError` on a tree inherited across a `fork()`.
+        """
+
+class Publisher:
+    """A claimed edge. Use as a context manager; the claim releases on exit."""
+
+    def __enter__(self) -> Publisher: ...
+    def __exit__(self, *args: object) -> bool: ...
+    def release(self) -> None:
+        """Drop the claim now, rather than at an unspecified finalization."""
+
+    def push(self, stamp_ns: int, quat7: list[float], /) -> None:
+        """Publish `[qw, qx, qy, qz, tx, ty, tz]` at `stamp_ns`."""
+
+    def push_many(
+        self, stamps: NDArray[np.int64], poses: NDArray[np.float64], /
+    ) -> None:
+        """Publish `(N,)` stamps and `(N, 7)` poses in one crossing."""
+
+class Tree:
+    """A transform tree. Obtain with `tf_tree.open()` or `tf_tree.build()`."""
+
+    def plan(self, target: str, source: str, /) -> Plan:
+        """Compile a path from `source` to `target`.
+
+        Compile once and reuse: the path walk and per-edge metadata lookup
+        happen here, not per sample.
+        """
+
+    def publisher(self, child: str, parent: str, /) -> Publisher:
+        """Claim `child`'s edge. Argument order is **(child, parent)**."""
+
+    def lookup(self, target: str, source: str, stamp_ns: int, /) -> NDArray[np.float64]:
+        """One transform, without compiling a plan first.
+
+        The plan is cached per *thread*. Prefer `tree.plan(...)` in a loop —
+        this pays a cache probe per call and a compiled plan pays nothing.
+        """
+
+    def freeze(
+        self, path: str | os.PathLike[str], /, *, source: str | None = ...
+    ) -> None:
+        """Write this tree to `path` as a frozen `.tft` (`PHASE5.md` §2.3).
+
+        The file *is* the arena: `open_file` maps it back with no parse and no
+        fixups, and the lookups it answers are bit-identical to this tree's.
+
+        Replacing `path` is atomic — the bytes land in a sibling temporary and
+        are renamed over it — so an interrupted freeze leaves the previous index
+        intact instead of a half-written one under the name somebody will open
+        next week.
+
+        `source` is the recording these poses came from; it is recorded in the
+        manifest as `null` when there is none. Linux only.
+
+        The GIL is released for the copy, so a background freeze does not stall
+        the threads servicing your progress bar or socket.
+        """
+
+    def span(self, target: str, source: str, /) -> tuple[int, int] | None:
+        """The interval, in nanoseconds, over which `plan(target, source)` answers.
+
+        `LatestCommon` generalised to a range: the *intersection* of every
+        dynamic edge's retained window, so the lower end is a `max` and the
+        upper end a `min`. It is the query to reach for when a lookup fails at
+        a stamp, because the answer is nearly always "one edge on the path had
+        not started yet".
+
+        Three distinct answers:
+
+        * `(t0, t1)` with `t0 <= t1` — answerable there, nowhere else.
+        * `(t0, t1)` with `t0 > t1` — the windows do not overlap. That is a real
+          answer, not an error: `t0 <= t <= t1` is correctly false everywhere.
+        * `None` — every step on the path is static (or the path is empty), so
+          the plan answers at *any* stamp and there is no finite interval.
+
+        Raises `NoDataError`, naming the edge's two **frames**, when an edge on
+        the path has no samples at all — which is a different situation from a
+        non-overlapping window and calls for a different fix. Raises
+        `TopologyChangedError` if the tree was re-parented under the call.
+
+        On a live tree the answer is a snapshot that ages immediately, exactly
+        as `Plan.latest` does.
+        """
+
+    def frames(self) -> list[str]:
+        """The frame names on this tree, in declaration order.
+
+        The cheap way to see what is in an arena without shelling out to
+        `tf_tree doctor`. Frame identity is append-only, so a name that appears
+        here will never be removed or renumbered — but on a *live* shared arena
+        a peer process can add one under you, so treat the list as a snapshot,
+        exactly as `Plan.latest` and `Tree.span` already are.
+
+        A name longer than 48 bytes was truncated when it was interned; the
+        stored form is what comes back.
+
+        **The list is not guaranteed to be free of duplicates.** If a peer
+        process stalls mid-intern and another rescues the slot, the loser's
+        record stays written but unreferenced, so the same name can appear at
+        two ids. Rare — it needs the rescue path — but it means `len()` is an
+        upper bound and `dict(zip(tree.frames(), ...))` can lose an entry.
+
+        Raises `TfTreeError` on a tree inherited across a `fork()` — the child's
+        mapping is gone, so there is nothing to list.
+        """
+
+    def edges(self) -> list[tuple[str, str]]:
+        """The edges on this tree, as `(parent, child)` name pairs.
+
+        `(parent, child)` is the order `tf_tree.build` and `tf_tree.open(
+        create=...)` take. It is deliberately *not* `Tree.publisher`'s
+        `(child, parent)` order: an edge list silently reversed builds a tree
+        that is upside down and still perfectly valid.
+
+        **This is the parent/child graph, not a round trip.** The list does not
+        say whether an edge is static or dynamic, and `tf_tree.build` has no way
+        to declare a static one — so feeding it back reproduces the graph, but
+        every static edge comes back as a dynamic edge with no samples, and a
+        lookup crossing one raises `NoDataError` instead of returning the
+        constant it had. On a tree you built with `tf_tree.build` every edge is
+        already dynamic and the distinction cannot arise; on a `.tft` or on an
+        arena a Rust or C peer created, it can.
+
+        **Names only** — no rate, no jitter, no gaps, no sample count. Those are
+        `PHASE5.md` §4.2's `ds.edges()` and are held back until the counting
+        pass that can answer them honestly exists: a ring knows what it
+        *retained*, which is not what the publisher produced, and a rate derived
+        from the one and reported as the other is worse than no rate at all.
+
+        Raises `TfTreeError` on a tree inherited across a `fork()`.
+        """
+
+    def instance_uuid(self) -> str:
+        """Which arena instance this is, as 32 hex characters.
+
+        All-zero in-process. Two processes that resolved the same *name* can
+        still hold different segments; this is what tells them apart.
+
+        Raises `TfTreeError` on a tree inherited across a `fork()`, rather than
+        returning the all-zero value the child's poison mapping holds — which is
+        the spelling that means "in-process", so two peers chasing a split brain
+        would conclude they had never been shared. `repr()` does not raise; it
+        prints `detached-by-fork` in place of the instance.
+        """
+
+    def is_shared(self) -> bool:
+        """Whether this tree's arena is shared with other processes."""
+
+    def is_writable(self) -> bool:
+        """Whether this process may publish into this tree."""
+
+def build(
+    edges: list[tuple[str, str]],
+    *,
+    capacity: int = ...,
+    interp: Literal["sclerp", "lerpslerp"] = ...,
+    frame_headroom: int = ...,
+) -> Tree:
+    """An in-process tree from `(parent, child)` edges.
+
+    Topology is builder-time (decision `0004`), so there is no `declare_*` on a
+    live tree: the layout is a property of the arena, fixed when it is created.
+
+    `interp` defaults to `"sclerp"` — the SE(3) screw geodesic, which is the
+    engine's own default and the only policy with an exact derivative, so
+    `plan.at(stamps, layout="quat_twist")` works on a tree built this way.
+
+    Pass `interp="lerpslerp"` for `tf2`-bit-compatible interpolation
+    (translation LERP + rotation SLERP). It is not right-invariant —
+    interpolating `T0 @ C, T1 @ C` is not `interp(T0, T1) @ C` — and it has no
+    exact body twist, so `layout="quat_twist"` over such an edge raises
+    `DerivativesUnavailableError`.
+
+    This binding hard-coded `"lerpslerp"` until now, diverging from Rust with no
+    measurement behind it; `PROJECT.md` §5 D5 requires one, so the default moved
+    rather than the rule.
+    """
+
+def push(
+    tree: Tree, child: str, parent: str, stamp_ns: int, quat7: list[float], /
+) -> None:
+    """Publish `[qw, qx, qy, qz, tx, ty, tz]` onto an edge at `stamp_ns`.
+
+    Takes the engine's own representation rather than a 4x4: a *nearly* rigid
+    matrix — which is what arrives after any floating-point round trip — has no
+    exact conversion back, only a projection.
+    """
+
+def open_arena(
+    *,
+    name: str | None = ...,
+    domain: int | None = ...,
+    mode: Literal["ro", "rw"] = ...,
+    create: list[tuple[str, str]] | None = ...,
+    capacity: int = ...,
+    interp: Literal["sclerp", "lerpslerp"] = ...,
+    frame_headroom: int = ...,
+) -> Tree:
+    """Attach to a running arena. Exported as `tf_tree.open`.
+
+    `mode="ro"` by default and `create=None`: a consumer must be incapable of
+    corrupting a robot's tree (the MMU enforces it), and a notebook started
+    before the robot must fail loudly rather than create an empty arena the
+    real publisher then refuses to join.
+
+    Pass `create=[(parent, child), ...]` — the same edge list `build` takes —
+    to create the arena when it is absent. An arena is sized from its declared
+    edges, so there is no way to create one without saying what is in it; that
+    is why this is an edge list rather than a boolean. **It requires
+    `mode="rw"`** and is refused otherwise, so a read-only consumer still
+    cannot bring an arena into existence.
+
+    `capacity` and `interp` describe the edges being created; both are
+    `build`'s, with the same defaults. Without `create` they describe nothing —
+    but `interp` is still validated, so a misspelling raises here exactly as it
+    does in `build` rather than being silently discarded.
+    """
+
+def open_file(path: str | os.PathLike[str], /) -> Tree:
+    """Open a frozen `.tft` and read it as an ordinary `Tree` (`PHASE5.md` §4.1).
+
+    Opening is an `mmap`, so it costs microseconds and no parse — and it hands
+    back the **same** `Tree` a live arena does. `plan`, `at`, `at_into`,
+    `adaptive`, `latest` and `span` are the objects that were already there,
+    with the same semantics and bit-identical results. There is no offline API
+    to learn.
+
+    The tree is permanently read-only: `is_writable()` is `False` and
+    `publisher()` refuses, because the mapping is `PROT_READ` and a store
+    through it would be a fault rather than an error.
+
+    Raises `FileNotFoundError` (and its `OSError` siblings) for a path problem,
+    and `TfTreeError` for a file that is not a readable `.tft` — a layout or
+    format mismatch names both values and says to re-freeze, since a `.tft` is a
+    cache and not an archive.
+
+    **Dataloader pattern (§4.3).** Documented, not shipped: a
+    `torch.utils.data.Dataset` subclass would bind this package to a framework
+    version for no benefit, and the pattern is four lines::
+
+        class Frames(Dataset):
+            def __init__(self, path):
+                self.path, self.ds = path, None
+
+            def __getitem__(self, i):
+                if self.ds is None:                    # per worker
+                    self.ds = tf_tree.open_file(self.path)
+                ...
+
+    Open it **in the worker, not in the parent**. A `Tree` cannot be pickled,
+    and a `DataLoader` with `num_workers > 0` sends the dataset object to its
+    workers — by pickle under `spawn` and `forkserver`, which is CPython 3.14's
+    default start method on Linux. The lazy `None` is what keeps the object
+    picklable.
+
+    Under a plain `fork` an inherited `.tft` mapping does keep working: it is
+    `MAP_PRIVATE | PROT_READ` and is deliberately *not* poisoned at fork, unlike
+    a shared-memory attach. So the rule is about picklability, not about the
+    arena going away — §4.3 gives the fork-poisoning reason and that reason does
+    not apply to a frozen file.
+
+    Sixteen workers that each open the same file share one set of clean
+    page-cache pages, so the marginal cost per worker is about zero. That is the
+    entire argument for `.tft` (§2.2), and opening once in the parent and
+    passing poses down instead gives it up.
+    """
+
+def from_sec(seconds: float, /) -> int:
+    """Nanoseconds from float seconds. Lossy above ~10^7 s.
+
+    Prefer the exact converters: `from_parts` for a `(sec, nanosec)` pair and
+    `from_ros` for a `builtin_interfaces/Time`. Neither takes a float.
+    """
+
+def from_parts(sec: int, nanosec: int, /) -> int:
+    """Exact nanoseconds from a `(sec, nanosec)` pair.
+
+    Raises `ValueError` for a `nanosec` outside `[0, 1e9)` — **refused, not
+    normalised** — and for a sum outside `int64` — **refused, not wrapped**.
+    Both alternatives produce a stamp that looks perfectly well formed, which
+    is the failure this converter exists to prevent.
+    """
+
+def from_ros(stamp: object, /) -> int:
+    """Exact nanoseconds from a ROS 2 `builtin_interfaces/Time`.
+
+    Never via `to_sec()`: the message is `{int32 sec, uint32 nanosec}` and
+    converts exactly. Duck-typed on `.sec` and `.nanosec`, so `rclpy` is not a
+    dependency of this wheel and must not become one.
+
+    Refusals are `from_parts`'s.
+    """
+
+def has_shared_memory() -> bool:
+    """Whether this build can share a tree between processes."""
+
+__version__: str
+"""This extension's version, compiled in from the crate manifest.
+
+`importlib.metadata.version("transform_tree")` is the canonical answer and reads a
+different file — `pyproject.toml`'s `[project] version` against this one's
+`Cargo.toml`. `tests/python/test_version.py` asserts the two agree, which is
+the only thing that keeps them from drifting.
+"""
+
+def arena_format_version() -> int:
+    """This build's arena format version — the *set of fields* in the header.
+
+    3 as of `PHASE5.md` §1. A different one is never compatible: there is no
+    conversion layer, so every participant is rebuilt from one commit and
+    restarted together.
+    """
+
+def arena_layout_hash() -> int:
+    """This build's arena layout hash — the *geometry*.
+
+    Checked on attach beside `arena_format_version()`, and a mismatch on either
+    is refused. Two builds agreeing on the version and disagreeing on the hash
+    disagree about *where* things are, which is worse than disagreeing about
+    what they are.
+
+    An `int`, because it is compared rather than read. For a report write
+    `f"0x{tf_tree.arena_layout_hash():08X}"` — the literal `0x` matters, since
+    Python's `{:#010X}` produces `0X…` and would not match what
+    `tft doctor --explain-version` prints.
+    """