simulo-interfaces 0.22.0__tar.gz → 0.24.0__tar.gz

{simulo_interfaces-0.22.0/src/simulo_interfaces.egg-info → simulo_interfaces-0.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo-interfaces
-Version: 0.22.0
+Version: 0.24.0
 Summary: Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause

{simulo_interfaces-0.22.0 → simulo_interfaces-0.24.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo-interfaces"
-version = "0.22.0"
+version = "0.24.0"
 description = "Typed Python contracts for the Simulo cloud robotics SDK and managed simulation runtime."
 readme = "PYPI.md"
 requires-python = ">=3.11"

{simulo_interfaces-0.22.0 → simulo_interfaces-0.24.0}/src/simulo/interfaces/authoring/__init__.py

@@ -1,13 +1,10 @@
 """Part C — the typed authoring surface.
 
-The **relocation and mirror destination** for the Simulo authoring value types.
-Each type here has exactly ONE definition — this one — shared by both
-distributions: the thin client authors these values at submit (torch-free,
-e.g. ``simulo.Pose(xyz=(1, 2, 3))``) and the backend executes them on the
-worker. There is no other copy and no re-export shim anywhere ("nuke as you
-go", per the owner's 2026-07-26 directive recorded in the plan): the former
-backend ``core`` modules for these types are deleted, so ``isinstance`` keeps
-working because only this definition exists.
+The relocation and mirror destination for shared authoring value types.
+Each value type has one definition here, used by the torch-free client when
+submitting a job and by the backend when executing it. Robot configuration
+records retain their existing backend import paths as re-exports of these
+same objects.
 
 Relocated so far — Wave C1: ``pose`` (``Pose``), ``materials`` (``Material``,
 ``SurfaceMaterial``), ``physics`` (``Physics``, ``Collision``, ``RigidPhysics``,
@@ -53,8 +50,9 @@ clearly in a submit-only installation.
 Two relocation mechanisms select which types land here and how (see the derived
 plan for the full worked example and rejected alternatives):
 
-* **RELOCATE** — the class definition MOVES here; the old ``core/<module>.py``
-  is deleted and every call site rewritten in the same PR (no re-export shims).
+* **RELOCATE** — the class definition MOVES here. Dependency-bearing modules
+  that also exposed a shared value type can re-export its one definition for
+  existing callers; dependency-free modules move with their call sites.
   Reserved for types with zero import-time *or* call-time dependency on
   anything that cannot live in a zero-dependency package.
 * **MIRROR** — a ``typing.Protocol`` (named ``*Protocol``, matching the
@@ -99,6 +97,7 @@ from simulo.interfaces.authoring.physics import (
     Physics,
     RigidPhysics,
 )
+from simulo.interfaces.authoring.policy_inputs import PolicyInput, PolicyInputSchema
 from simulo.interfaces.authoring.pose import Pose
 from simulo.interfaces.authoring.primitives import (
     Cone,
@@ -111,6 +110,7 @@ from simulo.interfaces.authoring.primitives import (
 from simulo.interfaces.authoring.prop import PropProtocol, PropStateProtocol
 from simulo.interfaces.authoring.record import RecordConfig
 from simulo.interfaces.authoring.robot import RobotProtocol, RobotStateProtocol
+from simulo.interfaces.authoring.robot_config import ActuatorGainsConfig, ArticulationConfig, JointConfig
 from simulo.interfaces.authoring.scene import SceneGroupProtocol, SceneProtocol
 from simulo.interfaces.authoring.sensor import CameraProtocol
 from simulo.interfaces.authoring.terrain import (
@@ -175,6 +175,8 @@ __all__ = [
     "RecordConfig",
     # injected policy input (dependency-free; loading is deferred to execution)
     "PolicyCheckpoint",
+    "PolicyInput",
+    "PolicyInputSchema",
     # visual
     "VisualMarkerBase",
     "AxesMarker",
@@ -185,6 +187,10 @@ __all__ = [
     # scene (MIRROR — the concrete classes live in the backend package)
     "SceneProtocol",
     "SceneGroupProtocol",
+    # robot configuration (dependency-free owning definitions)
+    "ActuatorGainsConfig",
+    "ArticulationConfig",
+    "JointConfig",
     # robot / prop / sensor / actuator (MIRROR — the concrete classes live in
     # the backend package and explicitly inherit these Protocols)
     "RobotProtocol",

simulo_interfaces-0.24.0/src/simulo/interfaces/authoring/policy_inputs.py

@@ -0,0 +1,207 @@
+"""Dependency-free declarations for raw actor and critic inputs.
+
+Images must be batched RGB uint8 NHWC. The contract requires future trainer
+and export consumers to convert the current minibatch to NCHW float and divide
+by 255; ``center`` also subtracts 0.5. These transforms belong in the actor's
+graph. This module checks declarations and raw values, not graph behavior.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass
+from typing import Any, Literal
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PolicyInput:
+    """One named input, with ``shape`` excluding the environment batch.
+
+    Names match ``[A-Za-z][A-Za-z0-9_]*``; shape dimensions are positive.
+    Tuple and list shapes are accepted and stored as tuples. Defaults are
+    ``dtype="float32"``, ``kind="numeric"`` and ``preprocessing="none"``.
+    Numeric inputs require float32, no camera and no preprocessing. Image
+    inputs require uint8, shape ``(H, W, 3)`` and a nonblank camera scene name:
+    the last segment of ``scene.add(camera, at="/World/<name>")``. Full paths
+    are rejected. LearningEnv setup requires that camera's purpose to be
+    ``"policy"``. Two policy cameras cannot share a scene name.
+    """
+
+    name: str
+    shape: tuple[int, ...]
+    dtype: str = "float32"
+    kind: Literal["numeric", "image"] = "numeric"
+    camera: str | None = None
+    preprocessing: Literal["none", "center"] = "none"
+
+    def __post_init__(self) -> None:
+        label = f"Input {self.name!r}"
+        if isinstance(self.shape, list):
+            object.__setattr__(self, "shape", tuple(self.shape))
+        if not isinstance(self.name, str) or not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]*", self.name):
+            raise ValueError(f"{label}: name must start with a letter and contain only letters, digits or underscores.")
+        if (
+            not isinstance(self.shape, tuple)
+            or not self.shape
+            or any(type(dim) is not int or dim <= 0 for dim in self.shape)
+        ):
+            raise ValueError(f"{label}: shape must be a nonempty tuple of positive dimensions, excluding batch.")
+        if self.kind not in ("numeric", "image"):
+            raise ValueError(f"{label}: kind must be 'numeric' or 'image'.")
+        if self.preprocessing not in ("none", "center"):
+            raise ValueError(f"{label}: preprocessing must be 'none' or 'center'.")
+        if self.kind == "image":
+            if self.dtype != "uint8":
+                raise ValueError(f"{label}: image dtype must be uint8 RGB NHWC, got {self.dtype!r}.")
+            if len(self.shape) != 3 or self.shape[-1] != 3:
+                raise ValueError(f"{label}: image shape must be (H, W, 3) RGB NHWC, excluding batch, got {self.shape}.")
+            if not isinstance(self.camera, str) or not self.camera.strip():
+                raise ValueError(f"{label}: image inputs require a camera identity.")
+            if "/" in self.camera or self.camera != self.camera.strip():
+                raise ValueError(f"{label}: camera must be a scene name, the last segment of scene.add(..., at=...).")
+        elif self.dtype != "float32" or self.camera is not None or self.preprocessing != "none":
+            raise ValueError(f"{label}: numeric inputs require float32, no camera, and preprocessing='none'.")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return JSON metadata, converting the stored tuple shape to a list."""
+        return {**asdict(self), "shape": list(self.shape)}
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> PolicyInput:
+        """Parse JSON, converting list shapes to tuples; reject unknown fields."""
+        if not isinstance(value, Mapping):
+            raise ValueError("Input declaration must be an object.")
+        allowed = {"name", "shape", "dtype", "kind", "camera", "preprocessing"}
+        if set(value) - allowed or not {"name", "shape"} <= set(value):
+            raise ValueError(f"Input {value.get('name')!r}: declaration has missing or unknown fields.")
+        shape = value["shape"]
+        if not isinstance(shape, (list, tuple)):
+            raise ValueError(f"Input {value['name']!r}: shape must be an array of positive dimensions.")
+        return cls(**{**value, "shape": tuple(shape)})
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PolicyInputSchema:
+    """Ordered actor inputs and optional separate training-only critic inputs.
+
+    ``critic=None`` means the critic uses exactly the actor declarations.
+    Future export and playback consumers must use only ``actor``. A critic
+    declaration sharing an actor name must be identical. Actor inputs omitted
+    from an explicit critic are not supplied to that critic. Order is part of
+    checkpoint compatibility, including numeric concatenation order.
+    """
+
+    actor: tuple[PolicyInput, ...]
+    critic: tuple[PolicyInput, ...] | None = None
+
+    def __post_init__(self) -> None:
+        for role, inputs in (("actor", self.actor), ("critic", self.critic_inputs)):
+            if not isinstance(inputs, tuple) or not inputs:
+                raise ValueError(f"{role} inputs must be a nonempty tuple of PolicyInput declarations.")
+            seen: set[str] = set()
+            for spec in inputs:
+                if not isinstance(spec, PolicyInput):
+                    raise ValueError(f"{role} inputs must contain PolicyInput declarations.")
+                if spec.name in seen:
+                    raise ValueError(f"{role} input {spec.name!r}: duplicate input name.")
+                seen.add(spec.name)
+        actor = {spec.name: spec for spec in self.actor}
+        for spec in self.critic_inputs:
+            if spec.name in actor and spec != actor[spec.name]:
+                raise ValueError(
+                    f"critic input {spec.name!r}: declaration contradicts the actor input of the same name."
+                )
+
+    @property
+    def critic_inputs(self) -> tuple[PolicyInput, ...]:
+        """Effective critic declarations, defaulting to actor inputs."""
+        return self.actor if self.critic is None else self.critic
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the actor/critic schema for a checkpoint sidecar."""
+        return {
+            "actor": [spec.to_dict() for spec in self.actor],
+            "critic": None if self.critic is None else [spec.to_dict() for spec in self.critic],
+        }
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> PolicyInputSchema:
+        """Parse a schema without permitting undeclared metadata."""
+        if not isinstance(value, Mapping) or set(value) != {"actor", "critic"}:
+            raise ValueError("Policy input schema requires exactly actor and critic fields.")
+        actor, critic = value["actor"], value["critic"]
+        if not isinstance(actor, (list, tuple)) or (critic is not None and not isinstance(critic, (list, tuple))):
+            raise ValueError("Policy input schema actor and critic must be arrays (critic may be null).")
+        return cls(
+            actor=tuple(PolicyInput.from_dict(spec) for spec in actor),
+            critic=None if critic is None else tuple(PolicyInput.from_dict(spec) for spec in critic),
+        )
+
+    @property
+    def fingerprint(self) -> str:
+        """SHA-256 of ordered inputs, including camera and preprocessing.
+
+        An omitted critic and an explicitly identical critic are equivalent.
+        Batch size is absent, so a checkpoint can change parallelism.
+        """
+
+        def canonical(spec: PolicyInput) -> dict[str, Any]:
+            # Pin v1's subset: future defaulted fields do not invalidate hashes.
+            return {name: getattr(spec, name) for name in ("name", "shape", "dtype", "kind", "camera", "preprocessing")}
+
+        metadata = {
+            "version": "simulo.policy-input-fingerprint.v1",
+            "actor": [canonical(spec) for spec in self.actor],
+            "critic": [canonical(spec) for spec in self.critic_inputs],
+        }
+        return hashlib.sha256(json.dumps(metadata, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+    def validate_values(
+        self,
+        actor: Any,
+        critic: Any,
+        *,
+        batch_size: int | None = None,
+    ) -> None:
+        """Check raw names, shapes, dtypes and batch size at LearningEnv._init_spaces.
+
+        Values need only ``shape`` and ``dtype`` attributes. No engine or tensor
+        package is imported. One declared numeric input may use the legacy
+        tensor return; multiple or image inputs require a named mapping. Values
+        must have a leading num_envs batch. Failures raise ValueError naming the
+        role and input. Legacy tasks with no schema are not checked by setup.
+        """
+        expected_batch = batch_size
+        for role, specs, values in (("actor", self.actor, actor), ("critic", self.critic_inputs, critic)):
+            if not isinstance(values, Mapping):
+                if len(specs) != 1 or specs[0].kind != "numeric":
+                    raise ValueError(f"{role} input {specs[0].name!r}: named inputs require a mapping.")
+                values = {specs[0].name: values}
+            declared = {spec.name for spec in specs}
+            for name in values:
+                if name not in declared:
+                    raise ValueError(f"{role} input {name!r}: unknown input name.")
+            for spec in specs:
+                if spec.name not in values:
+                    raise ValueError(f"{role} input {spec.name!r}: missing input.")
+                value = values[spec.name]
+                shape = tuple(getattr(value, "shape", ()))
+                if (
+                    len(shape) != len(spec.shape) + 1
+                    or shape[1:] != spec.shape
+                    or type(shape[0]) is not int
+                    or shape[0] <= 0
+                ):
+                    raise ValueError(
+                        f"{role} input {spec.name!r}: expected batched shape (N, {spec.shape}), got {shape}."
+                    )
+                if expected_batch is None:
+                    expected_batch = shape[0]
+                if shape[0] != expected_batch:
+                    raise ValueError(f"{role} input {spec.name!r}: expected batch {expected_batch}, got {shape[0]}.")
+                dtype = str(getattr(value, "dtype", "")).removeprefix("torch.")
+                if dtype != spec.dtype:
+                    raise ValueError(f"{role} input {spec.name!r}: expected dtype {spec.dtype}, got {dtype!r}.")

{simulo_interfaces-0.22.0 → simulo_interfaces-0.24.0}/src/simulo/interfaces/authoring/prop.py

@@ -154,15 +154,21 @@ class PropProtocol(Protocol):
 
     @property
     def default_pose(self) -> TensorLike:
-        """The prop's spawn pose in the **world** frame, ``(num_envs, 7)``.
+        """The prop's spawn pose in the **world** frame.
 
-        The pose the prop was authored at, already offset by each
-        environment's own origin — so it is directly comparable with
-        ``state.pose`` and directly usable as the base for a randomised
-        reset. Index it with the environments being reset
-        (``prop.default_pose[env_ids]``), perturb, and write it back with
+        For a prop added with ``per_environment=True`` (the default), the pose
+        has shape ``(num_envs, 7)`` and includes each environment's origin, so
+        it is directly comparable with ``state.pose`` and directly usable as
+        the base for a randomised reset. Index it with the environments being
+        reset (``prop.default_pose[env_ids]``), perturb, and write it back with
         :meth:`set_pose`.
 
+        For a prop added with ``per_environment=False``, this is one row
+        containing its authored world pose with no environment origin. A
+        shared prop is supported only when the scene has one environment;
+        scene building refuses ``per_environment=False`` for a prop when
+        ``num_envs > 1``.
+
         Raises ``RuntimeError`` until the simulation runtime has attached the
         prop.
         """

{simulo_interfaces-0.22.0 → simulo_interfaces-0.24.0}/src/simulo/interfaces/authoring/record.py

@@ -44,10 +44,13 @@ fingerprint that overrides the auto-collected one when present).
 
 from __future__ import annotations
 
+import math
 import os
+import sys
 from dataclasses import dataclass, field
+from numbers import Real
 from pathlib import Path
-from typing import Any, Dict, Literal, Mapping, Optional, Sequence, Tuple, Union
+from typing import Any, Dict, Literal, Mapping, Optional, Sequence, SupportsFloat, Tuple, Union
 
 # All include_* field names this config exposes. Centralizing avoids drift
 # between the dataclass declaration, _PROFILE_DEFAULTS, and resolve_includes.
@@ -192,6 +195,11 @@ class RecordConfig:
     profile precedence can distinguish "user passed False" from "default
     None". Do not edit defaults to plain ``bool`` — the silent-default
     mitigation depends on the tri-state.
+
+    ``record_all_envs`` expands numeric recording data only. Policy camera
+    video always uses ``env_indices`` (default: environment 0), so host frame
+    buffers and encoder count are bounded by the selected environments and
+    declared cameras, independently of the total environment count.
     """
 
     output_path: Optional[Union[str, "os.PathLike[str]", Path]] = None
@@ -253,7 +261,14 @@ class RecordConfig:
     video_fallback: Literal["software", "error"] = "software"
     video_codec: Literal["h264", "hevc", "av1"] = "h264"
     video_bitrate: Optional[str] = "8M"
-    video_fps: Optional[int] = 30
+    # ``None`` leaves cadence to the frame producer. The encoder then uses its
+    # documented 30 fps default, but the recorder omits ``video_fps`` from
+    # /run/start because packet timestamps, not an encoder setting, describe
+    # that producer-owned cadence. Callers such as evaluation filming set the
+    # measured cadence explicitly.
+    # Values must also fit a finite IEEE-754 double because both supported
+    # encoders and the MCAP JSON record use that representation.
+    video_fps: Optional[SupportsFloat] = None
     video_gop: Optional[int] = 30
     video_storage: Literal["embedded", "sidecar"] = "embedded"
     # When True (default), the recorder writes a parallel
@@ -300,6 +315,24 @@ class RecordConfig:
             raise ValueError(f"RecordConfig.profile must be one of {VALID_PROFILES}; got {self.profile!r}")
         if self.record_every_n_steps < 1:
             raise ValueError(f"RecordConfig.record_every_n_steps must be >= 1; got {self.record_every_n_steps}")
+        try:
+            video_fps = None if self.video_fps is None else float(self.video_fps)
+        except (OverflowError, TypeError, ValueError):
+            video_fps = None
+        if self.video_fps is not None and (
+            isinstance(self.video_fps, bool)
+            or not isinstance(self.video_fps, Real)
+            or video_fps is None
+            or not math.isfinite(video_fps)
+            # 0.1 fps is a policy floor that keeps rates sensible; ffmpeg's
+            # rational conversion only rounds to zero far below it.
+            or video_fps < 0.1
+            or video_fps > sys.float_info.max
+        ):
+            raise ValueError(
+                "RecordConfig.video_fps must be a finite real number representable by the encoder and at least 0.1 "
+                f"when set; got {self.video_fps!r}"
+            )
         # env_indices: accept any sequence of ints, including a torch tensor —
         # but normalize to a tuple of ints for hashability + reproducibility.
         try:

{simulo_interfaces-0.22.0 → simulo_interfaces-0.24.0}/src/simulo/interfaces/authoring/robot.py

@@ -7,7 +7,7 @@ and reset paths all reach through a live engine handle), so its
 *implementation* cannot live in a zero-dependency package. What CAN live here
 is its declared public surface: this Protocol names exactly what authoring
 code may rely on when it holds a robot — construction-time configuration,
-joint/body queries, command targets, state reads, and reset.
+joint/body queries, command targets, default state, live state reads, and reset.
 
 The backend's concrete ``Robot`` class explicitly inherits this Protocol
 (nominal conformance). Enforcement is the standard four layers for a mirror —
@@ -23,15 +23,16 @@ The Protocol stays structural for any other implementer.
 
 ``state`` is DECLARED, as ``RobotStateProtocol`` — the grouped live-state
 contract. It is the supported, typed way to read a robot's simulation state
-(``robot.state.joint_positions``, ``robot.state.pose``, …): six read-only,
+(``robot.state.joint_positions``, ``robot.state.pose``, …): eight read-only,
 batched members whose names are plain English rather than engine vocabulary.
-The members are LIVE VIEWS — each read goes straight through to the
-simulation's own buffers, at the same cost as reaching through the
-``internals`` escape hatch, with no copy and no per-access container
-allocation — so reading them inside a training loop is free of hidden
-overhead. Unlike ``internals``, these six names ARE a compatibility promise:
-they keep working across engine upgrades, because the backend maps each one
-to whatever the engine calls it.
+Six members are zero-copy live views of the simulation's buffers. The two
+base-frame velocity members are different: the engine rotates the current
+world-frame velocities into the base frame on every read, returning a new
+tensor. That small computation and allocation are the cost of those two
+accesses, and writing into either result does not reach the simulation.
+Unlike ``internals``, all eight names ARE a compatibility promise: they keep
+working across engine upgrades, because the backend maps each one to whatever
+the engine calls it.
 
 Deliberate scoping notes, so they are not mistaken for drift (each is an
 entry in the backend conformance test's documented-omissions allowlist):
@@ -63,32 +64,37 @@ from typing import Any, Dict, List, Optional, Protocol, Tuple, runtime_checkable
 
 from simulo.interfaces.authoring.asset import AssetSource
 from simulo.interfaces.authoring.pose import Pose
+from simulo.interfaces.authoring.robot_config import ArticulationConfig, JointConfig
 from simulo.interfaces.runtime.tensors import TensorLike
 
 
 @runtime_checkable
 class RobotStateProtocol(Protocol):
-    """The live robot-state contract — batched, read-only, zero-copy.
+    """The live robot-state contract — batched and read-only.
 
     Obtained from a robot as ``robot.state``; never constructed directly.
-    Each member is a live view of the simulation's own state buffers: reading
-    one returns the current values without copying, and the same access works
-    identically inside a training loop's hot path. All members carry the
-    environment batch as their leading dimension (the scene's ``num_envs``).
+    Six members (``pose``, the two world-frame velocities, and the three
+    ``joint_*`` members) are zero-copy live views of the simulation's own
+    buffers. ``linear_velocity_in_base_frame`` and
+    ``angular_velocity_in_base_frame`` are computed from the current base
+    orientation on every read. Each of those reads returns a new tensor,
+    costs a small computation, and cannot modify the simulation when written
+    into. All members carry the environment batch as their leading dimension
+    (the scene's ``num_envs``).
 
     **Read a member each time you need it — do not hold the returned tensor
-    across steps, and do not write into it.** The tensor IS the simulation's
-    own memory: the engine refreshes most of these buffers by rebinding them
-    to new tensors, so a tensor held across a step can silently serve stale
-    values, and writing into one writes into the simulation. The accessor
-    (``robot.state`` itself) may be held freely; the tensors its members
-    return should be re-read at each use.
+    across steps, and do not write into it.** The six live-view tensors share
+    simulation memory, and writing into one writes into the simulation. The
+    engine can also rebind those buffers, while the base-frame members are
+    recomputed, so a tensor held across a step can silently serve stale values.
+    The accessor (``robot.state`` itself) may be held freely; the tensors its
+    members return should be re-read at each use.
 
     Members raise ``RuntimeError`` until the simulation runtime has attached
     the robot — read them from ``on_start`` onward. The ``state`` accessor
     itself is always available and is the same object on every access.
 
-    These six names are a compatibility promise: they keep working across
+    These eight names are a compatibility promise: they keep working across
     engine upgrades. For anything not named here, the ``internals`` escape
     hatch remains available — explicitly unstable, at your own risk.
     """
@@ -111,6 +117,24 @@ class RobotStateProtocol(Protocol):
         ``[wx, wy, wz]``."""
         ...
 
+    @property
+    def linear_velocity_in_base_frame(self) -> TensorLike:
+        """Base linear velocity expressed in the base frame, shape
+        ``(num_envs, 3)`` in m/s with columns ``[vx, vy, vz]``. Available
+        from ``on_start`` onward. Computed from the current base orientation
+        on every read; each read returns a new tensor, costs a small
+        computation, and writing into it does not reach the simulation."""
+        ...
+
+    @property
+    def angular_velocity_in_base_frame(self) -> TensorLike:
+        """Base angular velocity expressed in the base frame, shape
+        ``(num_envs, 3)`` in rad/s with columns ``[wx, wy, wz]``. Available
+        from ``on_start`` onward. Computed from the current base orientation
+        on every read; each read returns a new tensor, costs a small
+        computation, and writing into it does not reach the simulation."""
+        ...
+
     @property
     def joint_positions(self) -> TensorLike:
         """Joint positions (rad or m), shape ``(num_envs, num_joints)``."""
@@ -146,7 +170,7 @@ class RobotProtocol(Protocol):
     """Model source (USD or URDF) defining the robot."""
 
     initial_pose: Pose
-    """Pose the robot spawns at, in the world frame (identity when not given)."""
+    """Pose the robot spawns at (identity when not given). For a robot copied into each environment, the position is measured from that environment's origin, and default_pose reports it with the origin added. For some catalog robots, such as the cartpole, the identity pose keeps the catalog model's own spawn height; any other pose replaces it. A robot added under a Transform spawns at the Transform's position."""
 
     collision_enabled: bool
     """Whether collision detection is enabled."""
@@ -160,17 +184,21 @@ class RobotProtocol(Protocol):
     scale: Tuple[float, float, float]
     """Per-axis spawn scale factor."""
 
-    articulation: Any
+    articulation: ArticulationConfig
     """Articulation physics and control configuration."""
 
-    joint_config: Optional[List[Any]]
+    joint_config: Optional[List[JointConfig]]
     """Optional per-joint configurations."""
 
     disable_gravity: bool
     """If ``True``, gravity is disabled for this robot."""
 
     actuator_gains: Optional[Dict[str, Any]]
-    """Optional mapping of actuator-group names to gain configurations."""
+    """Optional mapping of actuator-group names to gain configurations.
+
+    Catalog robots support only the ``"all_joints"`` key; other keys are ignored
+    with a warning.
+    """
 
     # -- Identity and attachment ------------------------------------------
 
@@ -203,9 +231,49 @@ class RobotProtocol(Protocol):
         """The grouped live robot state — the supported, typed state surface.
 
         Always available (the accessor is the same object on every access);
-        its members read straight through to the simulation's state buffers
-        and raise ``RuntimeError`` until the simulation runtime has attached
-        the robot — read them from ``on_start`` onward.
+        six members read straight through to the simulation's state buffers,
+        while the two base-frame velocity members are computed into new
+        tensors on every read. Members raise ``RuntimeError`` until the
+        simulation runtime has attached the robot — read them from
+        ``on_start`` onward.
+        """
+        ...
+
+    @property
+    def default_joint_positions(self) -> TensorLike:
+        """Joint positions that :meth:`reset` writes, shape
+        ``(num_envs, num_joints)`` in rad for hinge joints and m for slider
+        joints. Columns use the same order as ``state.joint_positions`` and
+        the indices returned by :meth:`find_joints`. Available from
+        ``on_start`` onward. Each read returns a new tensor, so writing into
+        it cannot change a later reset."""
+        ...
+
+    @property
+    def default_joint_velocities(self) -> TensorLike:
+        """Joint velocities that :meth:`reset` writes, shape
+        ``(num_envs, num_joints)`` in rad/s for hinge joints and m/s for
+        slider joints. Columns use the same order as
+        ``state.joint_positions`` and the indices returned by
+        :meth:`find_joints`. Available from ``on_start`` onward. Each read
+        returns a new tensor, so writing into it cannot change a later
+        reset."""
+        ...
+
+    @property
+    def default_pose(self) -> TensorLike:
+        """Base pose that :meth:`reset` writes in the world frame.
+
+        Columns are ``[x, y, z, qw, qx, qy, qz]``: position in m followed by a
+        w-first unit quaternion. For a robot added with
+        ``per_environment=True`` (the default), the shape is ``(num_envs, 7)``
+        and each environment's origin is included. For a robot added with
+        ``per_environment=False``, this is one row containing its authored
+        world pose with no environment origin. A shared robot is supported
+        only when the scene has one environment; scene building refuses
+        ``per_environment=False`` for a robot when ``num_envs > 1``. Available
+        from ``on_start`` onward. Each read returns a new tensor, so writing
+        into it cannot change a later reset.
         """
         ...