xlab-api 0.1.0__py3-none-any.whl

xlab_api/__init__.py

@@ -0,0 +1,66 @@
+"""Public engine-neutral XLab schemas and type declarations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import spec
+
+API_VERSION = "0.1"
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        value = getattr(spec, name)
+    except AttributeError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    globals()[name] = value
+    return value
+
+
+__all__ = [
+    "API_VERSION",
+    "UNIVERSAL_KINDS",
+    "ActionTermSpec",
+    "AgentSpec",
+    "ArticulationRef",
+    "BackendAsset",
+    "ClockDomainSpec",
+    "CollisionExclusionRef",
+    "CommandTermSpec",
+    "ComponentLifecycleSpec",
+    "ContactSensorRef",
+    "CurriculumTermSpec",
+    "DoneTermSpec",
+    "EntityRef",
+    "EventTermSpec",
+    "Grid3dPointsRef",
+    "JointProperties",
+    "LifecycleSpec",
+    "MdpSpec",
+    "MotionReferenceRef",
+    "NativeSensorRef",
+    "NoiseSpec",
+    "ObsGroupSpec",
+    "ObsTermSpec",
+    "RayCasterRef",
+    "RayPatternRef",
+    "Requirement",
+    "ResolvedClockDomain",
+    "RewardTermSpec",
+    "RigidObjectRef",
+    "RobotSpec",
+    "SceneSpec",
+    "SimSpec",
+    "SubTerrainSpec",
+    "SymmetricAugmentationSpec",
+    "TaskSpec",
+    "TermSpec",
+    "TerrainGeneratorSpec",
+    "TerrainSpec",
+    "VirtualObstacleRef",
+    "VolumePointsRef",
+    "freeze_task_spec",
+    "portability_report",
+    "resolve_lifecycle_contract",
+]

xlab_api/data.py

@@ -0,0 +1,90 @@
+"""Portable dataset URIs and local data-root resolution."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path, PurePosixPath
+from urllib.parse import unquote, urlsplit
+
+DATA_ROOT_ENV = "XLAB_DATA_ROOT"
+DATASET_SCHEME = "dataset"
+
+
+def is_dataset_uri(value: str | os.PathLike[str]) -> bool:
+    """Return whether ``value`` uses XLab's portable dataset URI scheme."""
+    return os.fspath(value).startswith(f"{DATASET_SCHEME}://")
+
+
+def dataset_root() -> Path:
+    """Return the configured local root for portable dataset URIs."""
+    declared = os.environ.get(DATA_ROOT_ENV, "~/Datasets")
+    return Path(declared).expanduser().resolve()
+
+
+def _dataset_relative_path(value: str) -> Path:
+    parsed = urlsplit(value)
+    if parsed.scheme != DATASET_SCHEME or not parsed.netloc:
+        raise ValueError(
+            f"Dataset URI must have the form dataset://collection/path, got {value!r}."
+        )
+    if (
+        parsed.query
+        or parsed.fragment
+        or parsed.username
+        or parsed.password
+        or parsed.port
+    ):
+        raise ValueError(f"Dataset URI contains unsupported URL fields: {value!r}.")
+    authority = unquote(parsed.netloc)
+    decoded_path = unquote(parsed.path)
+    if any(separator in authority for separator in ("/", "\\")) or "\\" in decoded_path:
+        raise ValueError(
+            f"Dataset URI contains an encoded or non-portable path separator: {value!r}."
+        )
+    components = (authority, *PurePosixPath(decoded_path).parts)
+    relative_parts = tuple(part for part in components if part not in {"", "/"})
+    if not relative_parts or any(part in {".", ".."} for part in relative_parts):
+        raise ValueError(
+            f"Dataset URI must not contain traversal components: {value!r}."
+        )
+    return Path(*relative_parts)
+
+
+def resolve_data_path(
+    value: str | os.PathLike[str],
+    *,
+    relative_to: str | os.PathLike[str] | None = None,
+) -> Path:
+    """Resolve a portable dataset URI or a readable legacy filesystem path.
+
+    ``dataset://collection/path`` is rooted at :envvar:`XLAB_DATA_ROOT`,
+    which defaults to ``~/Datasets``. Plain paths retain their historical
+    ``~`` behavior. Relative plain paths can be anchored with ``relative_to``.
+    Resolution does not require the target to exist so preflight can report
+    missing optional resources without changing the declaration.
+    """
+    declared = os.fspath(value)
+    if is_dataset_uri(declared):
+        root = dataset_root()
+        resolved = (root / _dataset_relative_path(declared)).resolve()
+        try:
+            resolved.relative_to(root)
+        except ValueError as exc:
+            raise ValueError(
+                f"Dataset URI resolves outside {DATA_ROOT_ENV}: {declared!r}."
+            ) from exc
+        return resolved
+
+    path = Path(declared).expanduser()
+    if relative_to is not None and not path.is_absolute():
+        path = Path(relative_to).expanduser() / path
+    return path.resolve()
+
+
+__all__ = [
+    "DATASET_SCHEME",
+    "DATA_ROOT_ENV",
+    "dataset_root",
+    "is_dataset_uri",
+    "resolve_data_path",
+]

xlab_api/py.typed

@@ -0,0 +1 @@
+

xlab_api/spec/__init__.py

@@ -0,0 +1,118 @@
+"""Engine-agnostic declaration layer.
+
+Nothing here may import a physics engine, directly or transitively. A task is declared once in
+these types and compiled to a native environment by the backend for whichever engine is running,
+so anything that reaches for an engine at this level has already lost the property that makes the
+declaration portable. Engine isolation is an explicit package boundary.
+
+:class:`~xlab_api.spec.task.TaskSpec` is the entry point: a whole task, produced by a frontend
+that read some project's native definition and consumed by the backend for the engine in use.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+_EXPORTS = {
+    "ArticulationRef": ("articulation", "ArticulationRef"),
+    "Requirement": ("capability", "Requirement"),
+    "UNIVERSAL_KINDS": ("entity", "UNIVERSAL_KINDS"),
+    "EntityRef": ("entity", "EntityRef"),
+    "freeze_task_spec": ("freeze", "freeze_task_spec"),
+    "ClockDomainSpec": ("lifecycle", "ClockDomainSpec"),
+    "ComponentLifecycleSpec": ("lifecycle", "ComponentLifecycleSpec"),
+    "LifecycleSpec": ("lifecycle", "LifecycleSpec"),
+    "ResolvedClockDomain": ("lifecycle", "ResolvedClockDomain"),
+    "resolve_lifecycle_contract": ("lifecycle", "resolve_lifecycle_contract"),
+    "ActionTermSpec": ("mdp", "ActionTermSpec"),
+    "CommandTermSpec": ("mdp", "CommandTermSpec"),
+    "CurriculumTermSpec": ("mdp", "CurriculumTermSpec"),
+    "DoneTermSpec": ("mdp", "DoneTermSpec"),
+    "EventTermSpec": ("mdp", "EventTermSpec"),
+    "MdpSpec": ("mdp", "MdpSpec"),
+    "NoiseSpec": ("mdp", "NoiseSpec"),
+    "ObsGroupSpec": ("mdp", "ObsGroupSpec"),
+    "ObsTermSpec": ("mdp", "ObsTermSpec"),
+    "RewardTermSpec": ("mdp", "RewardTermSpec"),
+    "TermSpec": ("mdp", "TermSpec"),
+    "portability_report": ("portability", "portability_report"),
+    "RigidObjectRef": ("rigid_object", "RigidObjectRef"),
+    "CollisionExclusionRef": ("relations", "CollisionExclusionRef"),
+    "BackendAsset": ("robot", "BackendAsset"),
+    "JointProperties": ("robot", "JointProperties"),
+    "RobotSpec": ("robot", "RobotSpec"),
+    "ContactSensorRef": ("sensor", "ContactSensorRef"),
+    "Grid3dPointsRef": ("sensor", "Grid3dPointsRef"),
+    "MotionReferenceRef": ("sensor", "MotionReferenceRef"),
+    "NativeSensorRef": ("sensor", "NativeSensorRef"),
+    "RayCasterRef": ("sensor", "RayCasterRef"),
+    "RayPatternRef": ("sensor", "RayPatternRef"),
+    "SymmetricAugmentationSpec": ("sensor", "SymmetricAugmentationSpec"),
+    "VirtualObstacleRef": ("sensor", "VirtualObstacleRef"),
+    "VolumePointsRef": ("sensor", "VolumePointsRef"),
+    "AgentSpec": ("task", "AgentSpec"),
+    "SceneSpec": ("task", "SceneSpec"),
+    "SimSpec": ("task", "SimSpec"),
+    "SubTerrainSpec": ("task", "SubTerrainSpec"),
+    "TaskSpec": ("task", "TaskSpec"),
+    "TerrainGeneratorSpec": ("task", "TerrainGeneratorSpec"),
+    "TerrainSpec": ("task", "TerrainSpec"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        module_name, attribute = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    value = getattr(import_module(f"{__name__}.{module_name}"), attribute)
+    globals()[name] = value
+    return value
+
+
+__all__ = [
+    "UNIVERSAL_KINDS",
+    "ActionTermSpec",
+    "AgentSpec",
+    "ArticulationRef",
+    "BackendAsset",
+    "ClockDomainSpec",
+    "CollisionExclusionRef",
+    "CommandTermSpec",
+    "ComponentLifecycleSpec",
+    "ContactSensorRef",
+    "CurriculumTermSpec",
+    "DoneTermSpec",
+    "EntityRef",
+    "EventTermSpec",
+    "Grid3dPointsRef",
+    "JointProperties",
+    "LifecycleSpec",
+    "MdpSpec",
+    "MotionReferenceRef",
+    "NativeSensorRef",
+    "NoiseSpec",
+    "ObsGroupSpec",
+    "ObsTermSpec",
+    "RayCasterRef",
+    "RayPatternRef",
+    "Requirement",
+    "ResolvedClockDomain",
+    "RewardTermSpec",
+    "RigidObjectRef",
+    "RobotSpec",
+    "SceneSpec",
+    "SimSpec",
+    "SubTerrainSpec",
+    "SymmetricAugmentationSpec",
+    "TaskSpec",
+    "TermSpec",
+    "TerrainGeneratorSpec",
+    "TerrainSpec",
+    "VirtualObstacleRef",
+    "VolumePointsRef",
+    "freeze_task_spec",
+    "portability_report",
+    "resolve_lifecycle_contract",
+]

xlab_api/spec/_names.py

@@ -0,0 +1,15 @@
+"""Small name-collection helpers shared by declaration modules."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+
+def as_name_tuple(names: str | Sequence[str]) -> tuple[str, ...]:
+    """Normalize one name or an ordered name sequence to an immutable tuple."""
+    if isinstance(names, str):
+        return (names,)
+    return tuple(names)
+
+
+__all__ = ["as_name_tuple"]

xlab_api/spec/articulation.py

@@ -0,0 +1,34 @@
+"""Additional articulated scene entities with canonical joint schemas."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .robot import RobotSpec
+
+
+@dataclass(frozen=True)
+class ArticulationRef:
+    """A named non-primary articulation materialized from a :class:`RobotSpec`.
+
+    ``RobotSpec.joint_names`` remains the canonical DFS axis. Reusing that
+    schema makes policy and observation selectors independent of each native
+    simulator's articulation order.
+    """
+
+    name: str
+    schema: RobotSpec
+
+    def __post_init__(self) -> None:
+        if not self.name or not self.name.isidentifier():
+            raise ValueError(
+                f"Additional articulation names must be Python identifiers, got {self.name!r}."
+            )
+        if self.name in {"robot", "terrain"}:
+            raise ValueError(
+                f"Additional articulation name {self.name!r} is reserved by the scene."
+            )
+        self.schema.validate()
+
+
+__all__ = ["ArticulationRef"]

xlab_api/spec/capability.py

@@ -0,0 +1,198 @@
+"""Capability vocabulary and task requirements shared by tasks and engines.
+
+Capabilities are open, namespaced strings. Engine plugins register what they
+provide, while task terms declare both a capability and how strongly they
+require it. Keeping both sides of that protocol here prevents the declaration
+layer from depending on the engine implementation package.
+
+"Skip what the engine cannot do" is only safe when the task gets to say which things it can afford
+to lose. Dropping a friction randomisation costs some robustness; dropping an observation changes
+the shape of the policy input, and dropping a reward changes what is being optimised while the run
+still looks healthy. One level cannot cover both, so terms carry a :class:`Requirement`, and the
+compiler acts on it.
+
+The defaults follow from that, and are set on each term class rather than chosen per task:
+
+===================  ==========  ==========================================================
+family               default     why
+===================  ==========  ==========================================================
+observation          REQUIRED    absence changes the network's input width and meaning
+action               REQUIRED    absence means the policy cannot act
+termination          REQUIRED    absence changes the episode structure
+command              REQUIRED    an observation term reads it
+reward               OPTIONAL    losing a regulariser is survivable -- but must be recorded
+event / DR           OPTIONAL    this is where engine capability actually differs
+curriculum           OPTIONAL    --
+===================  ==========  ==========================================================
+
+A task overrides per term where its own judgement differs: a locomotion task that is only stable
+because of one particular reward should mark that reward REQUIRED and find out at startup.
+
+OPTIONAL does not mean silent. Every skip is recorded in the compilation's ``Resolution`` and
+printed once as a table at startup, because a silently dropped reward term is a changed objective,
+and the resulting policy is otherwise indistinguishable from a healthy one. ``--strict-capabilities``
+promotes every OPTIONAL to REQUIRED for CI and for runs that are meant to be comparable.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from enum import Enum
+from types import MappingProxyType
+
+_REGISTRY: dict[str, str] = {}
+
+
+class UnknownCapability(KeyError):
+    """Raised when a capability identifier was never registered."""
+
+
+def capability(identifier: str, description: str) -> str:
+    """Register one namespaced capability and return its identifier."""
+    if "." not in identifier:
+        raise ValueError(f"{identifier!r} needs a namespace, as in 'contact.air_time'")
+    if not description.strip():
+        raise ValueError(
+            f"{identifier!r} was registered without saying what providing it means"
+        )
+    existing = _REGISTRY.get(identifier)
+    if existing is not None and existing != description:
+        raise ValueError(f"{identifier!r} is already registered as {existing!r}")
+    _REGISTRY[identifier] = description
+    return identifier
+
+
+def known() -> Mapping[str, str]:
+    """Return every registered capability and its meaning."""
+    return MappingProxyType(dict(_REGISTRY))
+
+
+def check_known(values: Iterable[str]) -> None:
+    """Reject identifiers that no provider or shared vocabulary registered."""
+    unknown = sorted(set(values) - set(_REGISTRY))
+    if unknown:
+        raise UnknownCapability(
+            f"{unknown} are not registered capabilities. An engine package registers what it can do "
+            f"when it is imported; registered so far: {sorted(_REGISTRY)}"
+        )
+
+
+BATCHED_SIMULATION = capability(
+    "sim.batched", "Many environments stepped together in one call."
+)
+GPU_SIMULATION = capability(
+    "sim.gpu", "Physics runs on the GPU with state left in device memory."
+)
+PLANE_TERRAIN = capability("terrain.plane", "An infinite ground plane.")
+ROOT_STATE = capability("state.root", "Reading and writing a body's root pose.")
+ROOT_VELOCITY_WRITE = capability(
+    "state.root_velocity", "Writing a root velocity, frame qualified."
+)
+JOINT_STATE = capability(
+    "state.joint", "Reading and writing joint positions and velocities."
+)
+BODY_STATE = capability(
+    "state.body", "Per-body poses and velocities of an articulation."
+)
+IMPLICIT_POSITION_CONTROL = capability(
+    "control.position_implicit", "Joint position targets tracked by the solver."
+)
+EFFORT_CONTROL = capability("control.effort", "Direct joint torque commands.")
+CONTACT_ACTIVE = capability(
+    "contact.active", "Whether a body is currently touching something."
+)
+CONTACT_HISTORY = capability(
+    "contact.history", "Contact readings kept for several past steps."
+)
+CONTACT_AIR_TIME = capability(
+    "contact.air_time", "Durations a body has been in contact or in the air."
+)
+CONTACT_FORCE_VECTOR = capability(
+    "contact.force_vector", "Contact force as a vector rather than a magnitude."
+)
+DR_SLIDING_FRICTION = capability(
+    "dr.friction.sliding", "Randomising the sliding friction coefficient."
+)
+DR_RESTITUTION = capability("dr.restitution", "Randomising restitution.")
+BODY_MASS_PROPERTIES = capability(
+    "body.mass_properties", "Changing a body's mass or inertia after load."
+)
+EXTERNAL_WRENCH = capability(
+    "body.external_wrench", "Applying an external force or torque to a body."
+)
+HUMAN_VIEWER = capability("render.human", "An interactive viewer window.")
+RGB_ARRAY = capability("render.rgb_array", "Rendering frames to arrays.")
+
+
+@dataclass(frozen=True)
+class CapabilitySet:
+    """The validated capabilities provided by one engine plugin."""
+
+    values: frozenset[str]
+
+    @classmethod
+    def of(cls, values: Iterable[str]) -> CapabilitySet:
+        collected = frozenset(values)
+        check_known(collected)
+        return cls(collected)
+
+    def supports(self, capability: str) -> bool:
+        return capability in self.values
+
+    def require(self, required: Iterable[str], *, context: str) -> None:
+        required = frozenset(required)
+        check_known(required)
+        missing = required.difference(self.values)
+        if missing:
+            raise RuntimeError(
+                f"{context} requires unsupported engine capabilities: {', '.join(sorted(missing))}"
+            )
+
+
+class Requirement(str, Enum):
+    """What the compiler does when the engine cannot provide a term."""
+
+    REQUIRED = "required"
+    """Fail at startup. The task is not runnable on this engine and should say so immediately."""
+
+    OPTIONAL = "optional"
+    """Skip it, record it in the resolution, and report it in the startup summary."""
+
+    EMULATE = "emulate"
+    """Substitute the adapter's registered stand-in; fall back to OPTIONAL when it has none.
+
+    For terms whose effect can be approximated by other means -- a push event realised by writing
+    root velocity where an engine has no external-wrench API, say. The substitution is recorded
+    separately from a skip, because an emulated term is running *something*, and a later comparison
+    between engines needs to know which.
+    """
+
+
+__all__ = [
+    "BATCHED_SIMULATION",
+    "BODY_MASS_PROPERTIES",
+    "BODY_STATE",
+    "CONTACT_ACTIVE",
+    "CONTACT_AIR_TIME",
+    "CONTACT_FORCE_VECTOR",
+    "CONTACT_HISTORY",
+    "DR_RESTITUTION",
+    "DR_SLIDING_FRICTION",
+    "EFFORT_CONTROL",
+    "EXTERNAL_WRENCH",
+    "GPU_SIMULATION",
+    "HUMAN_VIEWER",
+    "IMPLICIT_POSITION_CONTROL",
+    "JOINT_STATE",
+    "PLANE_TERRAIN",
+    "RGB_ARRAY",
+    "ROOT_STATE",
+    "ROOT_VELOCITY_WRITE",
+    "CapabilitySet",
+    "Requirement",
+    "UnknownCapability",
+    "capability",
+    "check_known",
+    "known",
+]

xlab_api/spec/entity.py

@@ -0,0 +1,156 @@
+"""References to a subset of a scene entity, stated without naming an engine.
+
+An :class:`EntityRef` says *which parts of which entity* a term acts on -- these joints, those
+bodies -- and leaves it to the backend to turn that into the engine's own selector configuration.
+The translation happens once at compile time, so the runtime cost is nil and terms keep reading
+tensors directly.
+
+Selector kinds are open on purpose. Isaac Lab and mjlab agree on only two of them:
+
+===============  ==========================================================================
+engine           kinds its ``SceneEntityCfg`` accepts
+===============  ==========================================================================
+both             ``joint``, ``body``
+Isaac Lab only   ``fixed_tendon``, ``object_collection``
+mjlab only       ``actuator``, ``camera``, ``geom``, ``light``, ``material``, ``pair``,
+                 ``site``, ``tendon``
+===============  ==========================================================================
+
+Two kinds out of twelve. A fixed pair of ``joints`` / ``bodies`` fields would therefore be able to
+express Isaac Lab tasks and quietly lose everything an mjlab task says about geoms and sites, which
+is the direction this project has to support as well. So the common two get named fields for
+legibility and everything else goes in :attr:`other`, where the backend can either translate it or
+refuse loudly.
+
+Note that Isaac Lab's ``fixed_tendon`` and mjlab's ``tendon`` are related but not the same kind,
+and are deliberately not unified here; naming them apart keeps a backend from silently accepting a
+selector it cannot honour.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+
+__all__ = ["UNIVERSAL_KINDS", "EntityRef", "resolve_entity_names"]
+
+UNIVERSAL_KINDS: tuple[str, ...] = ("joint", "body")
+"""The only selector kinds every supported engine can express. Checked in the tests."""
+
+
+def _normalise(patterns: str | Sequence[str] | None) -> tuple[str, ...] | None:
+    """Accept a bare string the way both engines' ``SceneEntityCfg`` does."""
+    if patterns is None:
+        return None
+    if isinstance(patterns, str):
+        return (patterns,)
+    return tuple(patterns)
+
+
+def resolve_entity_names(
+    patterns: str | Sequence[str],
+    available_names: Sequence[str],
+    *,
+    preserve_order: bool,
+) -> tuple[str, ...]:
+    """Resolve selector patterns with the semantics shared by both engines.
+
+    ``preserve_order=False`` follows ``available_names``.  ``True`` groups matches by
+    pattern order while retaining ``available_names`` order inside each pattern.  A name may
+    match only one pattern and every pattern must match, matching both native selector helpers.
+    Keeping this tiny resolver in the declaration layer lets validation and compilation reason
+    about the selected tensor axis before either engine SDK is imported.
+    """
+    expressions = (patterns,) if isinstance(patterns, str) else tuple(patterns)
+    if not expressions:
+        raise ValueError("A selector was given no patterns.")
+
+    matches_by_pattern: list[list[str]] = [[] for _ in expressions]
+    source_order: list[str] = []
+    for name in available_names:
+        matching = [
+            index
+            for index, expression in enumerate(expressions)
+            if re.fullmatch(expression, name)
+        ]
+        if len(matching) > 1:
+            duplicate_patterns = tuple(expressions[index] for index in matching)
+            raise ValueError(
+                f"Entity name {name!r} matches multiple selector patterns: {duplicate_patterns!r}."
+            )
+        if matching:
+            matches_by_pattern[matching[0]].append(name)
+            source_order.append(name)
+
+    unmatched = [
+        expression
+        for expression, matches in zip(expressions, matches_by_pattern)
+        if not matches
+    ]
+    if unmatched:
+        raise ValueError(
+            f"Selector patterns match no entity names: {unmatched!r}. Available names: {tuple(available_names)!r}."
+        )
+    if not preserve_order:
+        return tuple(source_order)
+    return tuple(name for matches in matches_by_pattern for name in matches)
+
+
+@dataclass(frozen=True)
+class EntityRef:
+    """A subset of one scene entity, named by pattern rather than by index.
+
+    Patterns are regular expressions matched against the entity's own names, which is what both
+    engines do; the matching helper is byte-identical between them, so a pattern selects the same
+    thing either way.
+
+    Args:
+        entity: Key of the entity in the scene.
+        joints: Joint name patterns, or a single pattern.
+        bodies: Body name patterns, or a single pattern.
+        other: Patterns for selector kinds outside :data:`UNIVERSAL_KINDS`, keyed by kind. A
+            backend that cannot express a kind must reject the reference rather than drop it.
+        preserve_order: When true the selection follows the order of the patterns; when false it
+            follows the entity's own order. Note what the entity's own order is not: it is whatever
+            the engine built, which is a breadth-first walk under PhysX and model-file order under
+            MuJoCo, and those two disagree. D1's canonical depth-first order is therefore reached
+            only by passing the catalog's joint names explicitly with this flag set -- a bare ``.*``
+            preserves the order of a one-element pattern list and so changes nothing.
+    """
+
+    entity: str = "robot"
+    joints: str | Sequence[str] | None = None
+    bodies: str | Sequence[str] | None = None
+    other: Mapping[str, str | Sequence[str]] = field(default_factory=dict)
+    preserve_order: bool = False
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "joints", _normalise(self.joints))
+        object.__setattr__(self, "bodies", _normalise(self.bodies))
+        normalised = {
+            kind: _normalise(patterns) for kind, patterns in dict(self.other).items()
+        }
+        for kind, patterns in normalised.items():
+            if kind in UNIVERSAL_KINDS:
+                raise ValueError(
+                    f"'{kind}' has its own field on EntityRef; do not pass it through 'other'."
+                )
+            if not patterns:
+                raise ValueError(f"Selector '{kind}' was given no patterns.")
+        # Sorted so that two references built from equivalent mappings compare equal.
+        object.__setattr__(self, "other", dict(sorted(normalised.items())))
+
+    def selectors(self) -> dict[str, tuple[str, ...]]:
+        """Every selector on this reference, keyed by kind, in a single mapping."""
+        out: dict[str, tuple[str, ...]] = {}
+        if self.joints is not None:
+            out["joint"] = self.joints
+        if self.bodies is not None:
+            out["body"] = self.bodies
+        out.update(self.other)  # type: ignore[arg-type]
+        return out
+
+    def kinds(self) -> frozenset[str]:
+        """The selector kinds this reference uses. A backend checks it against what it supports."""
+        return frozenset(self.selectors())