Publish audited ActionCodec2 release files

runtime/physical/semantic.py

@@ -0,0 +1,377 @@
+"Canonical physical preprocessing for routed ActionCodec2 profiles."
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+from scipy.interpolate import CubicSpline, PchipInterpolator
+from scipy.spatial.transform import Rotation, RotationSpline
+
+from ._so3 import euler_xyz_to_quaternion as _euler_xyz_to_quaternion
+from ._so3 import multiply_quaternions as _quaternion_multiply
+from ._so3 import normalize_quaternion as _normalize_quaternion
+from ._so3 import quaternion_to_rotvec as _quaternion_to_rotvec
+from ._so3 import rotvec_to_quaternion as _rotvec_to_quaternion
+
+_INTERPOLATION_METHODS = {"linear", "pchip", "cubic"}
+
+
+def _validate_rate(value: float, name: str) -> float:
+    rate = float(value)
+    if not math.isfinite(rate) or rate <= 0.0:
+        raise ValueError(f"{name} must be positive and finite")
+    return rate
+
+
+def _quaternion_slerp(
+    left: np.ndarray, right: np.ndarray, weight: np.ndarray
+) -> np.ndarray:
+    
+    first = _normalize_quaternion(np.asarray(left, dtype=np.float64))
+    second = _normalize_quaternion(np.asarray(right, dtype=np.float64))
+    dot = np.sum(first * second, axis=1)
+    flip = dot < 0.0
+    second[flip] *= -1.0
+    dot = np.clip(np.abs(dot), 0.0, 1.0)
+    output = np.empty_like(first)
+    near = dot > 0.9995
+    output[near] = first[near] + weight[near, None] * (second[near] - first[near])
+    regular = ~near
+    if np.any(regular):
+        angle = np.arccos(dot[regular])
+        denominator = np.sin(angle)
+        w = weight[regular]
+        output[regular] = (
+            np.sin((1.0 - w) * angle)[:, None] / denominator[:, None] * first[regular]
+            + np.sin(w * angle)[:, None] / denominator[:, None] * second[regular]
+        )
+    return _normalize_quaternion(output)
+
+
+def resampled_horizon(length: int, *, source_hz: float, target_hz: float) -> int:
+    "Return the target control-step count for a regular source horizon."
+    if (
+        isinstance(length, bool)
+        or not isinstance(length, (int, np.integer))
+        or length < 1
+    ):
+        raise ValueError("a trajectory must contain at least one sample")
+    source_rate = _validate_rate(source_hz, "source_hz")
+    target_rate = _validate_rate(target_hz, "target_hz")
+    scaled = int(math.floor(int(length) * target_rate / source_rate + 0.5))
+    return max(1, scaled)
+
+
+def _target_times(
+    length: int,
+    source_hz: float,
+    target_hz: float,
+    *,
+    target_length: int | None,
+) -> np.ndarray:
+    count = (
+        resampled_horizon(length, source_hz=source_hz, target_hz=target_hz)
+        if target_length is None
+        else target_length
+    )
+    if isinstance(count, bool) or not isinstance(count, (int, np.integer)) or count < 1:
+        raise ValueError("target_length must be a positive integer")
+    return np.arange(int(count), dtype=np.float64) / target_hz
+
+
+def _guarded_natural_cubic(
+    source_time: np.ndarray,
+    values: np.ndarray,
+    target_time: np.ndarray,
+) -> np.ndarray:
+    
+    sampled = np.asarray(
+        CubicSpline(source_time, values, axis=0, bc_type="natural")(target_time),
+        dtype=np.float64,
+    )
+    lower = np.min(values, axis=0)
+    upper = np.max(values, axis=0)
+
+
+    tolerance = 1e-9 + 0.05 * (upper - lower)
+    fallback_axes = np.any(
+        (sampled < lower[None] - tolerance[None])
+        | (sampled > upper[None] + tolerance[None]),
+        axis=0,
+    )
+    if np.any(fallback_axes):
+        sampled[:, fallback_axes] = PchipInterpolator(
+            source_time, values[:, fallback_axes], axis=0
+        )(target_time)
+    return sampled
+
+
+def resample_uniform(
+    values: np.ndarray,
+    *,
+    source_hz: float,
+    target_hz: float,
+    kind: str = "linear",
+    target_length: int | None = None,
+    method: str = "linear",
+) -> np.ndarray:
+    "Resample one regular control-horizon trajectory onto a target clock."
+    source_rate = _validate_rate(source_hz, "source_hz")
+    target_rate = _validate_rate(target_hz, "target_hz")
+    array = np.asarray(values, dtype=np.float64)
+    if array.ndim != 2 or len(array) < 1 or not np.all(np.isfinite(array)):
+        raise ValueError("values must be a non-empty finite [T, D] array")
+    if kind not in {"linear", "hold", "pose_xyzw", "pose_euler_xyz"}:
+        raise ValueError("unsupported resampling kind")
+    if method not in _INTERPOLATION_METHODS:
+        raise ValueError(f"method must be one of {sorted(_INTERPOLATION_METHODS)}")
+    if kind == "pose_xyzw" and array.shape[1] != 7:
+        raise ValueError("pose_xyzw values must have shape [T, 7]")
+    if kind == "pose_euler_xyz" and array.shape[1] != 6:
+        raise ValueError("pose_euler_xyz values must have shape [T, 6]")
+    standard_length = resampled_horizon(
+        len(array), source_hz=source_rate, target_hz=target_rate
+    )
+    if source_rate == target_rate and target_length in {None, standard_length}:
+        if kind == "pose_euler_xyz":
+            array = np.concatenate(
+                (array[:, :3], _euler_xyz_to_quaternion(array[:, 3:6])), axis=1
+            )
+        return np.asarray(array, dtype=np.float32)
+
+    target_time = _target_times(
+        len(array), source_rate, target_rate, target_length=target_length
+    )
+    source_time = np.arange(len(array), dtype=np.float64) / source_rate
+    interpolation_time = np.minimum(target_time, source_time[-1])
+    source_position = target_time * source_rate
+    left = np.minimum(np.floor(source_position).astype(np.int64), len(array) - 1)
+    right = np.minimum(left + 1, len(array) - 1)
+    weight = source_position - left
+    if kind == "hold":
+        result = array[left]
+    else:
+        pose = kind in {"pose_xyzw", "pose_euler_xyz"}
+        continuous = array[:, :3] if pose else array
+        if len(array) == 1:
+            sampled = np.repeat(continuous, len(target_time), axis=0)
+        elif method == "pchip":
+            sampled = PchipInterpolator(source_time, continuous, axis=0)(
+                interpolation_time
+            )
+        elif method == "cubic":
+            sampled = _guarded_natural_cubic(
+                source_time, continuous, interpolation_time
+            )
+        else:
+            sampled = array[left, : continuous.shape[1]] + weight[:, None] * (
+                array[right, : continuous.shape[1]] - array[left, : continuous.shape[1]]
+            )
+        if not pose:
+            result = sampled
+        else:
+            quaternion = (
+                array[:, 3:7]
+                if kind == "pose_xyzw"
+                else _euler_xyz_to_quaternion(array[:, 3:6])
+            )
+            if len(array) == 1:
+                rotation = np.repeat(quaternion, len(target_time), axis=0)
+            elif method == "linear":
+                rotation = _quaternion_slerp(
+                    quaternion[left], quaternion[right], weight
+                )
+            else:
+                rotation = RotationSpline(source_time, Rotation.from_quat(quaternion))(
+                    interpolation_time
+                ).as_quat()
+            result = np.concatenate((sampled, rotation), axis=1)
+    return np.asarray(result, dtype=np.float32)
+
+
+def eef_pose_absolute(poses: np.ndarray) -> np.ndarray:
+    """Convert canonical ``xyz + xyzw`` state to ``xyz + rotation_vector``."""
+    values = np.asarray(poses, dtype=np.float64)
+    if values.ndim != 2 or values.shape[1] != 7 or not np.all(np.isfinite(values)):
+        raise ValueError("poses must be a finite [T, 7] array")
+    return np.asarray(
+        np.concatenate((values[:, :3], _quaternion_to_rotvec(values[:, 3:7])), axis=1),
+        dtype=np.float32,
+    )
+
+
+def eef_pose_components(poses: np.ndarray, representation: str) -> np.ndarray:
+    """Convert canonical ``xyz + xyzw`` poses to one registered source layout."""
+    values = np.asarray(poses, dtype=np.float64)
+    if values.ndim != 2 or values.shape[1] != 7 or not np.all(np.isfinite(values)):
+        raise ValueError("poses must be a finite [T, 7] array")
+    quaternion = _normalize_quaternion(values[:, 3:7])
+    if representation == "rotation_vector":
+        rotation = _quaternion_to_rotvec(quaternion)
+    elif representation == "euler_xyz":
+        rotation = Rotation.from_quat(quaternion).as_euler("xyz")
+    elif representation == "quaternion_xyzw":
+        rotation = quaternion
+    else:
+        raise ValueError("unsupported EEF rotation representation")
+    return np.asarray(
+        np.concatenate((values[:, :3], rotation), axis=1), dtype=np.float32
+    )
+
+
+def eef_pose_from_components(
+    position: np.ndarray,
+    rotation: np.ndarray,
+    representation: str,
+) -> np.ndarray:
+    "Build canonical ``xyz + xyzw`` poses from an explicit source layout."
+    translation = np.asarray(position, dtype=np.float64)
+    orientation = np.asarray(rotation, dtype=np.float64)
+    if translation.ndim != 2 or translation.shape[1] != 3 or len(translation) < 1:
+        raise ValueError("position must have non-empty shape [T, 3]")
+    if len(orientation) != len(translation) or not np.all(np.isfinite(translation)):
+        raise ValueError("position and rotation must have matching finite trajectories")
+    if representation == "rotation_vector":
+        if orientation.ndim != 2 or orientation.shape[1] != 3:
+            raise ValueError("rotation_vector must have shape [T, 3]")
+        quaternion = _rotvec_to_quaternion(orientation)
+    elif representation == "euler_xyz":
+        if orientation.ndim != 2 or orientation.shape[1] != 3:
+            raise ValueError("euler_xyz must have shape [T, 3]")
+        quaternion = _euler_xyz_to_quaternion(orientation)
+    elif representation == "quaternion_xyzw":
+        if orientation.ndim != 2 or orientation.shape[1] != 4:
+            raise ValueError("quaternion_xyzw must have shape [T, 4]")
+        quaternion = _normalize_quaternion(orientation)
+    else:
+        raise ValueError("unsupported EEF rotation representation")
+    if not np.all(np.isfinite(orientation)):
+        raise ValueError("position and rotation must be finite")
+    return np.asarray(
+        np.concatenate((translation, quaternion), axis=1), dtype=np.float32
+    )
+
+
+def eef_pose_local_absolute(
+    poses: np.ndarray, *, initial_pose: np.ndarray | None = None
+) -> np.ndarray:
+    "Express measured poses relative to an explicit or inferred initial pose."
+    values = np.asarray(poses, dtype=np.float64)
+    if (
+        values.ndim != 2
+        or values.shape[1] != 7
+        or len(values) < 1
+        or not np.all(np.isfinite(values))
+    ):
+        raise ValueError("poses must be a finite non-empty [T, 7] array")
+    if initial_pose is None:
+        initial = values[:1]
+    else:
+        initial = np.asarray(initial_pose, dtype=np.float64)
+        if initial.shape == (7,):
+            initial = initial[None]
+        if initial.shape != (1, 7) or not np.all(np.isfinite(initial)):
+            raise ValueError("initial_pose must be a finite [7] pose")
+    quaternion = _normalize_quaternion(values[:, 3:7])
+    initial_quaternion = _normalize_quaternion(initial[:, 3:7])
+    inverse_start = initial_quaternion.copy()
+    inverse_start[:, :3] *= -1.0
+    relative = _quaternion_multiply(
+        np.broadcast_to(inverse_start, quaternion.shape), quaternion
+    )
+    return np.asarray(
+        np.concatenate(
+            (values[:, :3] - initial[:, :3], _quaternion_to_rotvec(relative)), axis=1
+        ),
+        dtype=np.float32,
+    )
+
+
+def eef_pose_deltas(poses: np.ndarray) -> np.ndarray:
+    "Differentiate a local ``xyz + xyzw`` path from zero/identity."
+    values = np.asarray(poses, dtype=np.float64)
+    if (
+        values.ndim != 2
+        or values.shape[1] != 7
+        or len(values) < 1
+        or not np.all(np.isfinite(values))
+    ):
+        raise ValueError("poses must be a finite non-empty [T, 7] array")
+    quaternion = _normalize_quaternion(values[:, 3:7])
+    previous_position = np.concatenate((np.zeros((1, 3)), values[:-1, :3]), axis=0)
+    identity = np.asarray([[0.0, 0.0, 0.0, 1.0]], dtype=np.float64)
+    previous_quaternion = np.concatenate((identity, quaternion[:-1]), axis=0)
+    inverse_previous = previous_quaternion.copy()
+    inverse_previous[:, :3] *= -1.0
+    increment = _quaternion_multiply(inverse_previous, quaternion)
+    return np.asarray(
+        np.concatenate(
+            (values[:, :3] - previous_position, _quaternion_to_rotvec(increment)),
+            axis=1,
+        ),
+        dtype=np.float32,
+    )
+
+
+def eef_pose_from_local_absolute(
+    poses: np.ndarray, *, initial_pose: np.ndarray
+) -> np.ndarray:
+    """Attach an external initial pose to a local ``xyz + xyzw`` path."""
+    values = np.asarray(poses, dtype=np.float64)
+    initial = np.asarray(initial_pose, dtype=np.float64)
+    if (
+        values.ndim != 2
+        or values.shape[1] != 7
+        or len(values) < 1
+        or not np.all(np.isfinite(values))
+    ):
+        raise ValueError("poses must be a finite non-empty [T, 7] array")
+    if initial.shape == (7,):
+        initial = initial[None]
+    if initial.shape != (1, 7) or not np.all(np.isfinite(initial)):
+        raise ValueError("initial_pose must be a finite [7] pose")
+    local_quaternion = _normalize_quaternion(values[:, 3:7])
+    initial_quaternion = _normalize_quaternion(initial[:, 3:7])
+    quaternion = _quaternion_multiply(
+        np.broadcast_to(initial_quaternion, local_quaternion.shape), local_quaternion
+    )
+    return np.asarray(
+        np.concatenate((values[:, :3] + initial[:, :3], quaternion), axis=1),
+        dtype=np.float32,
+    )
+
+
+def integrate_eef_deltas(deltas: np.ndarray) -> np.ndarray:
+    "Integrate ``[dx,dy,dz,body-rotvec]`` from a zero/identity pose."
+    values = np.asarray(deltas, dtype=np.float64)
+    if values.ndim != 2 or values.shape[1] != 6 or not np.all(np.isfinite(values)):
+        raise ValueError("deltas must be a finite [T, 6] array")
+    if len(values) < 1:
+        raise ValueError("deltas must contain at least one step")
+    translation = np.cumsum(values[:, :3], axis=0)
+    increments = _rotvec_to_quaternion(values[:, 3:6])
+    orientation = np.empty((len(values), 4), dtype=np.float64)
+    current = np.asarray([[0.0, 0.0, 0.0, 1.0]], dtype=np.float64)
+    for index, increment in enumerate(increments):
+        current = _quaternion_multiply(current, increment[None])
+        orientation[index] = current[0]
+    return np.asarray(
+        np.concatenate((translation, orientation), axis=1), dtype=np.float32
+    )
+
+
+def binarize_gripper_actions(
+    values: np.ndarray,
+    *,
+    threshold: float,
+    open_is_high: bool,
+) -> np.ndarray:
+    """Map one controller gripper channel to canonical ``0=closed, 1=open``."""
+    array = np.asarray(values, dtype=np.float32)
+    if array.ndim != 2 or array.shape[1] != 1 or not np.all(np.isfinite(array)):
+        raise ValueError("gripper action must be a finite [T, 1] array")
+    if not math.isfinite(threshold):
+        raise ValueError("gripper threshold must be finite")
+    opened = array >= threshold if open_is_high else array <= threshold
+    return opened.astype(np.float32)

runtime/physical/trajectory.py

@@ -0,0 +1,130 @@
+"""Variable-width trajectory contract shared by statistics and fitting."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+import numpy as np
+
+from ..common._validation import active_dimensions
+from .configuration import ActionCodec2Config
+
+__all__ = ["ActiveTrajectory", "TrajectoryLike", "prepare_trajectory"]
+
+
+@dataclass(frozen=True)
+class ActiveTrajectory:
+    "One complete trajectory over an explicit subset of codebook dimensions."
+
+    values: np.ndarray
+    active_dims: tuple[int, ...]
+    previous_first_order: np.ndarray | None = None
+
+    def __init__(
+        self,
+        values: np.ndarray,
+        active_dims: Sequence[int],
+        *,
+        previous_first_order: np.ndarray | None = None,
+    ) -> None:
+        object.__setattr__(self, "values", np.asarray(values))
+        object.__setattr__(self, "active_dims", tuple(active_dims))
+        previous = (
+            None
+            if previous_first_order is None
+            else np.asarray(previous_first_order, dtype=np.float32)
+        )
+        if previous is not None and (
+            previous.shape != (len(self.active_dims),)
+            or not np.all(np.isfinite(previous))
+        ):
+            raise ValueError(
+                "previous_first_order must be finite with shape [D_active]"
+            )
+        object.__setattr__(self, "previous_first_order", previous)
+
+    @classmethod
+    def from_padded(
+        cls,
+        values: np.ndarray,
+        *,
+        active_dims: Sequence[int],
+        previous_first_order: np.ndarray | None = None,
+    ) -> ActiveTrajectory:
+        "Drop engineering-only dense padding before the semantic boundary."
+        array = np.asarray(values)
+        dims = tuple(int(value) for value in active_dims)
+        if array.ndim != 2 or not dims or min(dims) < 0 or max(dims) >= array.shape[1]:
+            raise ValueError(
+                "padded values and active_dims do not define a valid trajectory"
+            )
+        previous = (
+            None
+            if previous_first_order is None
+            else np.take(previous_first_order, dims)
+        )
+        return cls(np.take(array, dims, axis=1), dims, previous_first_order=previous)
+
+
+def trajectory_boundary(
+    trajectory: TrajectoryLike, config: ActionCodec2Config, active_dims: tuple[int, ...]
+) -> np.ndarray | None:
+    """Expand explicit compact state to ``[D]`` for fitting and validation."""
+    previous = getattr(trajectory, "previous_first_order", None)
+    active = set(active_dims)
+    required = any(
+        c.primitive_order == 2 and active.intersection(c.dims)
+        for c in config.physical.components.values()
+    )
+    if previous is None and required:
+        raise ValueError(
+            "second-order trajectories require explicit previous_first_order"
+        )
+    if previous is None and not any(
+        c.primitive_order == 2 for c in config.physical.components.values()
+    ):
+        return None
+    dense = np.zeros(config.physical.input_dim, dtype=np.float32)
+    if previous is not None:
+        dense[list(active_dims)] = previous
+    return dense
+
+
+TrajectoryLike = np.ndarray | ActiveTrajectory
+
+
+def prepare_trajectory(
+    trajectory: TrajectoryLike,
+    *,
+    dimension: int,
+    index: int,
+    dtype: np.dtype | type = np.float32,
+) -> tuple[np.ndarray, tuple[int, ...]]:
+    "Validate a trajectory and return compact values plus global dimension ids."
+    if isinstance(trajectory, ActiveTrajectory):
+        raw = trajectory.values
+        active_dims = trajectory.active_dims
+    else:
+        raw = trajectory
+        array = np.asarray(raw)
+        active_dims = tuple(range(array.shape[1])) if array.ndim == 2 else ()
+
+    values = np.asarray(raw, dtype=dtype)
+    if values.ndim != 2 or len(values) < 1 or values.shape[1] < 1:
+        raise ValueError(
+            f"trajectory {index} must have non-empty shape [T, D_active], got {values.shape}"
+        )
+    if len(active_dims) != values.shape[1]:
+        raise ValueError(
+            f"trajectory {index} active_dims has {len(active_dims)} entries for "
+            f"width {values.shape[1]}"
+        )
+    if any(isinstance(item, bool) or not isinstance(item, int) for item in active_dims):
+        raise ValueError(f"trajectory {index} active_dims must contain integers")
+    active_dims = active_dimensions(
+        active_dims, dimension, subject=f"trajectory {index} active_dims"
+    )
+    if not np.all(np.isfinite(values)):
+        raise ValueError(f"trajectory {index} contains a non-finite value")
+    return np.ascontiguousarray(values), active_dims

runtime/processing_actioncodec2.py

@@ -0,0 +1,429 @@
+"""Hugging Face processor over the shared ActionCodec2 frontend implementation."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import torch
+from transformers.feature_extraction_utils import BatchFeature
+from transformers.processing_utils import ProcessorMixin
+
+from .routing.defaults import CodecBuilder, ProfileBundleBuilder, builtin_action_spaces
+from .integration.hf import (
+    PROCESSOR_CONFIG_NAME,
+    ROUTER_ALLOW_PATTERNS,
+    ActionCodec2FrontendHFConfig,
+    resolve_pretrained_directory,
+    save_huggingface_metadata,
+    save_model_card,
+    upload_pretrained_directory,
+)
+from .routing.presets import PresetConfig
+from .routing.routing import ActionCodec2Router
+from .frontend.tokenizer import ActionCodec2Tokenizer
+
+
+def _saved_metadata(directory: Path) -> dict[str, Any]:
+    metadata = directory / PROCESSOR_CONFIG_NAME
+    return (
+        json.loads(metadata.read_text(encoding="utf-8")) if metadata.is_file() else {}
+    )
+
+
+def _fitted_status(profiles) -> str:
+    status = ", ".join(sorted(profiles)) or "none; call codec.fit(episodes)"
+    return f"Fitted profiles: {status}\n"
+
+
+class ActionCodec2(ActionCodec2Tokenizer, ProcessorMixin):
+    "Action-space-bound processor with lossless token serialization."
+
+    model_type = ActionCodec2FrontendHFConfig.model_type
+    model_input_names = ["input_ids"]
+
+    attributes = []
+
+    def __init__(
+        self,
+        backend: ActionCodec2Router | None = None,
+        *,
+        action_space: str,
+        primitive_order: int = 1,
+        bpe_scheme: str | None = None,
+        profile_configs: Mapping[str, object] | None = None,
+    ) -> None:
+        fresh = backend is None
+        if fresh:
+            backend = CodecBuilder(
+                primitive_order=primitive_order,
+                bpe_scheme=bpe_scheme,
+                profile_configs=profile_configs,
+            ).build()
+        elif (
+            primitive_order != 1
+            or bpe_scheme is not None
+            or profile_configs is not None
+        ):
+            raise ValueError(
+                "profile construction options cannot accompany an existing backend"
+            )
+        super().__init__(backend, action_space=action_space)
+        ProcessorMixin.__init__(self)
+        self._fitted_profiles = frozenset() if fresh else frozenset(backend.profiles)
+        self.training_report = None
+        self._source_directory = Path(__file__).parent
+
+    def __dir__(self):
+        inapplicable = {
+            "action_tokenizer",
+            "attributes",
+            "audio_tokenizer",
+            "chat_template",
+            "check_argument_for_proper_class",
+            "encode_kwargs",
+            "feature_extractor_class",
+            "from_args_and_dict",
+            "get_possibly_dynamic_module",
+            "get_processor_dict",
+            "model_input_names",
+            "model_type",
+            "optional_attributes",
+            "optional_call_args",
+            "apply_chat_template",
+            "post_process_image_text_to_text",
+            "pad_action_id",
+            "bos_blk_id",
+            "parts_meta",
+            "BAR_SENTINEL_TOKENS",
+            "push_to_hub",
+            "register_for_auto_class",
+            "tokenizer_class",
+            "to_dict",
+            "to_json_file",
+            "to_json_string",
+            "valid_processor_kwargs",
+            "validate_init_kwargs",
+        }
+        return [name for name in super().__dir__() if name not in inapplicable]
+
+    def __repr__(self) -> str:
+        return (
+            f"ActionCodec2(action_space={self.action_space.name!r}, "
+            f"D={self.action_dim}, vocab={self.action_tokenizer.vocab_size})"
+        )
+
+    @staticmethod
+    def builtin_action_spaces():
+        """Return the immutable named layout definitions shipped in the package."""
+        return builtin_action_spaces()
+
+    @classmethod
+    def from_profiles(cls, joint, eef, *, action_space: str, token_budgets=None):
+        "Bind an artifact assembled from existing joint/EEF profile directories."
+        router = ProfileBundleBuilder(joint, eef, token_budgets=token_budgets).build()
+        return cls(router, action_space=action_space)
+
+    def logits_processor(
+        self,
+        horizon: int,
+        *,
+        fps: float,
+        prompt_length: int,
+        eos_token_id: int,
+        token_offset: int = 0,
+        pad_token_id=None,
+    ):
+        "Create a Transformers LogitsProcessor for a fixed action horizon."
+        from .tokenization.generation import ActionCodec2LogitsProcessor
+
+        return ActionCodec2LogitsProcessor(
+            self,
+            horizon,
+            fps=fps,
+            prompt_length=prompt_length,
+            eos_token_id=eos_token_id,
+            token_offset=token_offset,
+            pad_token_id=pad_token_id,
+        )
+
+    def batch_decode(
+        self,
+        token_rows,
+        *,
+        fps=None,
+        current_state=None,
+        previous_first_order=None,
+        errors="raise",
+    ):
+        "Decode independent token rows, including different valid horizons."
+        self._require_fitted()
+        if errors not in ("raise", "return"):
+            raise ValueError("errors must be 'raise' or 'return'")
+        rows = list(token_rows)
+        current = (
+            None
+            if current_state is None
+            else np.asarray(
+                current_state.detach().cpu()
+                if isinstance(current_state, torch.Tensor)
+                else current_state
+            )
+        )
+        if current is not None and current.shape != (len(rows), self.action_dim):
+            raise ValueError(
+                f"current_state must have shape {(len(rows), self.action_dim)}"
+            )
+        previous = self._numpy_boundary(previous_first_order)
+        if previous is not None and any(
+            np.ndim(v) != 2 or len(v) != len(rows) for v in previous.values()
+        ):
+            raise ValueError(
+                "previous_first_order arrays must have batch dimension equal to token rows"
+            )
+        result = []
+        for index, row in enumerate(rows):
+            try:
+                decoded = self.decode(
+                    [row],
+                    fps=fps,
+                    current_state=None
+                    if current is None
+                    else current[index : index + 1],
+                    previous_first_order=None
+                    if previous is None
+                    else {k: v[index : index + 1] for k, v in previous.items()},
+                )
+            except ValueError as error:
+                error = ValueError(f"token row {index}: {error}")
+                if errors == "raise":
+                    raise error from None
+                decoded = error
+            result.append(decoded)
+        return result
+
+    @property
+    def fitted_profiles(self) -> frozenset[str]:
+        """Names of profiles fitted on data; persisted by save_pretrained()."""
+        return self._fitted_profiles
+
+    @property
+    def is_fitted(self) -> bool:
+        """Whether every profile used by the selected action space is fitted."""
+        return all(
+            c.space in self.fitted_profiles for c in self.action_space.components
+        )
+
+    def _require_fitted(self):
+        missing = {c.space for c in self.action_space.components} - self.fitted_profiles
+        if missing:
+            raise RuntimeError(
+                f"Unfitted profiles {sorted(missing)}; call codec.fit(episodes) first"
+            )
+
+    def _describe_action_spaces(self, action_dim: int | None = None) -> str:
+        return _fitted_status(self.fitted_profiles) + super()._describe_action_spaces(
+            action_dim
+        )
+
+    def for_action_space(self, name: str) -> ActionCodec2:
+        """Share current weights with a new binding; subsequent fit replaces only that instance."""
+        codec = super().for_action_space(name)
+        codec._fitted_profiles = self.fitted_profiles
+        codec.training_report = self.training_report
+        codec._source_directory = self._source_directory
+        return codec
+
+    def fit(
+        self,
+        episodes,
+        *,
+        fps: float | None = None,
+        current_state=None,
+        previous_first_order=None,
+        bootstrap_context: bool = False,
+        backend: str = "auto",
+        threads: int = 0,
+        batch_size: int = 256,
+        progress: bool = False,
+        max_cell_bytes: int | None = None,
+        work_dir: str | Path | None = None,
+    ) -> ActionCodec2:
+        "Fit physical vocabularies from actions in declared source layouts."
+
+
+        from .training.fitting import ActionCodec2Fitter
+
+        router, report = ActionCodec2Fitter(
+            self, bootstrap_context=bootstrap_context
+        ).fit(
+            episodes,
+            work_dir=work_dir,
+            metadata=dict(
+                fps=fps,
+                current_state=current_state,
+                previous_first_order=previous_first_order,
+            ),
+            backend=backend,
+            threads=threads,
+            batch_size=batch_size,
+            progress=progress,
+            max_cell_bytes=max_cell_bytes,
+        )
+        fitted = self.fitted_profiles | report["profiles"].keys()
+        replacement = type(self)(router, action_space=self.action_space.name)
+        replacement._fitted_profiles = frozenset(fitted)
+        replacement.training_report = report
+        replacement._source_directory = self._source_directory
+        replacement._warned_default_fps = self._warned_default_fps
+        self.__dict__.update(replacement.__dict__)
+        return self
+
+    def _encode_action_indices(self, action, encode_kwargs=None):
+        self._require_fitted()
+        return super()._encode_action_indices(action, encode_kwargs)
+
+    def _decode_action_indices(self, action_indices, **kwargs):
+        self._require_fitted()
+        return super()._decode_action_indices(action_indices, **kwargs)
+
+    def grammar(self, horizon: int, *, fps: float | None = None):
+        self._require_fitted()
+        return super().grammar(horizon, fps=fps)
+
+    def final_first_order(
+        self, action_token_ids, *, previous_first_order, executed_steps=None
+    ):
+        self._require_fitted()
+        return super().final_first_order(
+            action_token_ids,
+            previous_first_order=previous_first_order,
+            executed_steps=executed_steps,
+        )
+
+    @classmethod
+    def describe_pretrained(
+        cls,
+        pretrained_model_name_or_path: str | Path,
+        *,
+        action_dim: int | None = None,
+        **kwargs: Any,
+    ) -> str:
+        "Inspect a local/Hub artifact before choosing an action space."
+        directory = resolve_pretrained_directory(
+            pretrained_model_name_or_path,
+            allow_patterns=ROUTER_ALLOW_PATTERNS,
+            **kwargs,
+        )
+        router = ActionCodec2Router.from_pretrained(directory)
+        metadata = _saved_metadata(directory)
+        return _fitted_status(
+            metadata.get("fitted_profiles", router.profiles)
+        ) + router.describe_action_spaces(
+            selected=metadata.get("action_space"), action_dim=action_dim
+        )
+
+    @classmethod
+    def from_pretrained(
+        cls,
+        pretrained_model_name_or_path: str | Path,
+        *,
+        action_space: str | Path | PresetConfig | Mapping[str, object] | None = None,
+        **kwargs: Any,
+    ) -> ActionCodec2:
+        "Load a local/Hub artifact and restore or override its action space."
+        directory = resolve_pretrained_directory(
+            pretrained_model_name_or_path,
+            allow_patterns=ROUTER_ALLOW_PATTERNS,
+            **kwargs,
+        )
+        if action_space is None:
+            action_space = _saved_metadata(directory).get("action_space")
+        if action_space is None:
+            raise ValueError(
+                "action_space is required when loading an unbound router artifact. "
+                "First inspect its layouts with print(ActionCodec2.describe_pretrained(path)), "
+                "then pass action_space='NAME'; shape alone cannot identify physical meaning."
+            )
+        codec = super().from_pretrained(directory, action_space=action_space)
+        metadata = _saved_metadata(directory)
+        fitted = metadata.get("fitted_profiles", list(codec.action_tokenizer.profiles))
+        if not isinstance(fitted, list) or any(
+            not isinstance(name, str) or name not in codec.action_tokenizer.profiles
+            for name in fitted
+        ):
+            raise ValueError("invalid fitted_profiles in processor_config.json")
+        codec._fitted_profiles = frozenset(fitted)
+        codec._source_directory = directory
+        report_path = directory / "fit_report.json"
+        if report_path.is_file():
+            codec.training_report = json.loads(report_path.read_text(encoding="utf-8"))
+        return codec
+
+    def to_dict(self, legacy_serialization: bool = True) -> dict[str, object]:
+        "Return lightweight discovery metadata."
+        del legacy_serialization
+        return {
+            "processor_class": type(self).__name__,
+            "model_type": self.model_type,
+            "action_space": self.action_space.name,
+            "fitted_profiles": sorted(self.fitted_profiles),
+        }
+
+    def save_pretrained(
+        self, save_directory: str | Path, push_to_hub: bool = False, **kwargs: Any
+    ) -> list[str]:
+        """Save the complete router and the selected action-space binding."""
+        if not push_to_hub and kwargs:
+            raise TypeError(
+                f"unused save_pretrained keyword(s): {', '.join(sorted(kwargs))}"
+            )
+        from .integration.exporting import ArtifactExporter
+
+        directory = Path(save_directory)
+        save_model_card(directory, str(self))
+        files = self.action_tokenizer.save_pretrained(directory, include_code=False)
+        files.extend(
+            ArtifactExporter(
+                directory, source_directory=self._source_directory
+            ).export()
+        )
+        save_huggingface_metadata(
+            directory,
+            **self.to_dict(),
+            auto_map={"AutoProcessor": "processing_actioncodec2.ActionCodec2"},
+        )
+        report_path = directory / "fit_report.json"
+        if self.training_report is not None:
+            report_path.write_text(
+                json.dumps(self.training_report, indent=2) + "\n", encoding="utf-8"
+            )
+            files.append(str(report_path))
+        elif report_path.exists():
+            report_path.unlink()
+        if push_to_hub:
+            upload_pretrained_directory(directory, **kwargs)
+        return files
+
+    def __call__(
+        self,
+        action: torch.Tensor | np.ndarray,
+        *,
+        fps: float | None = None,
+        current_state: torch.Tensor | np.ndarray | None = None,
+        previous_first_order: Mapping[str, torch.Tensor | np.ndarray] | None = None,
+        encode_kwargs: dict | None = None,
+        return_tensors: str | None = None,
+    ) -> BatchFeature:
+        
+        rows = self.encode(
+            action,
+            fps=fps,
+            current_state=current_state,
+            previous_first_order=previous_first_order,
+            encode_kwargs=encode_kwargs,
+        )
+        return BatchFeature({"input_ids": rows}, tensor_type=return_tensors)

runtime/routing/__init__.py

@@ -0,0 +1 @@
+"""Internal routing components for ActionCodec2."""

runtime/routing/cache.py

@@ -0,0 +1,41 @@
+"""Small per-instance LRU caches; no global references to fitted codecs."""
+
+from collections import OrderedDict
+from collections.abc import MutableMapping
+from threading import RLock
+
+
+class BoundedCache(MutableMapping):
+    "Evict least-recently-used entries above a fixed capacity."
+
+    def __init__(self, capacity):
+        if type(capacity) is not int or capacity < 1:
+            raise ValueError("cache capacity must be a positive integer")
+        self.capacity = capacity
+        self._items = OrderedDict()
+        self._lock = RLock()
+
+    def __getitem__(self, key):
+        with self._lock:
+            value = self._items[key]
+            self._items.move_to_end(key)
+            return value
+
+    def __setitem__(self, key, value):
+        with self._lock:
+            self._items[key] = value
+            self._items.move_to_end(key)
+            while len(self._items) > self.capacity:
+                self._items.popitem(last=False)
+
+    def __delitem__(self, key):
+        with self._lock:
+            del self._items[key]
+
+    def __iter__(self):
+        with self._lock:
+            return iter(tuple(self._items))
+
+    def __len__(self):
+        with self._lock:
+            return len(self._items)

runtime/routing/defaults.py

@@ -0,0 +1,609 @@
+"""Package-owned configuration templates for fresh ActionCodec2 instances."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ..tokenization.bpe import BPESerializer, SetBPESerializer
+from ..physical.configuration import ActionCodec2Config
+from ..physical.physical_processor import ActionCodec2Processor
+from .presets import PresetConfig
+from .routing import ActionCodec2Router
+
+
+class CodecBuilder:
+    "Build unfitted physical profiles from packaged defaults or explicit configs."
+
+    def __init__(self, *, primitive_order=1, bpe_scheme=None, profile_configs=None):
+        if type(primitive_order) is not int or primitive_order not in (1, 2):
+            raise ValueError("primitive_order must be 1 or 2")
+        if bpe_scheme not in (None, "set_bpe", "bpe"):
+            raise ValueError("bpe_scheme must be 'set_bpe' or 'bpe'")
+        if profile_configs is not None and not isinstance(profile_configs, Mapping):
+            raise TypeError(
+                "profile_configs must map 'joint'/'eef' to physical configurations"
+            )
+        self.profile_configs = dict(profile_configs or {})
+        if set(self.profile_configs) - {"joint", "eef"}:
+            raise ValueError("profile_configs keys must be 'joint' or 'eef'")
+        self.primitive_order = primitive_order
+        self.bpe_scheme = bpe_scheme
+
+    def _config(self, name: str) -> ActionCodec2Config:
+        suffix = "" if self.primitive_order == 1 else "_second_order_pretrain_v2"
+        raw = self.profile_configs.get(name, _PROFILE_DEFAULTS[f"{name}{suffix}"])
+        if isinstance(raw, ActionCodec2Config):
+            config = raw
+        elif isinstance(raw, Mapping):
+            config = ActionCodec2Config.from_dict(raw)
+        else:
+            config = ActionCodec2Config.from_yaml(raw)
+        if config.train is None:
+            raise ValueError(f"{name} profile config requires a train section")
+        if self.bpe_scheme is not None:
+            payload = config.to_dict()
+            payload["set_bpe"]["scheme"] = self.bpe_scheme
+            if self.bpe_scheme == "bpe":
+                payload["train"]["bpe"]["spatial_vocab_size"] = payload["train"]["bpe"][
+                    "vocab_size"
+                ]
+            config = ActionCodec2Config.from_dict(payload)
+        return config
+
+    def build(self) -> ActionCodec2Router:
+        """Create primitive-only profiles; the public facade tracks fitted state."""
+        processors = {}
+        budgets = {}
+        for name in ("joint", "eef"):
+            config = self._config(name)
+
+
+            from ..training.training import build_primitives
+
+            primitives = build_primitives(config)
+            if config.set_bpe.scheme == "bpe":
+                serializer = BPESerializer(
+                    bins=primitives.bins, lookahead=config.set_bpe.lookahead, merges=()
+                )
+            else:
+                serializer = SetBPESerializer(
+                    bins=primitives.bins,
+                    lookahead=config.set_bpe.lookahead,
+                    spatial_merges=(),
+                    temporal_merges=(),
+                )
+            processors[name] = ActionCodec2Processor(config, primitives, serializer)
+            budgets[name] = config.train.bpe.vocab_size
+        presets = list(builtin_action_spaces().values())
+        return ActionCodec2Router.from_processors(
+            processors, token_budgets=budgets, presets=presets
+        )
+
+
+def builtin_action_spaces():
+    """Return a read-only name-to-preset mapping shipped in the installed package."""
+    from types import MappingProxyType
+
+    presets = [PresetConfig.from_dict(value) for value in _PRESET_DEFAULTS.values()]
+    return MappingProxyType({preset.name: preset for preset in presets})
+
+
+class ProfileBundleBuilder:
+    "Assemble two existing physical artifacts using their recorded vocabulary budgets."
+
+    def __init__(self, joint, eef, *, token_budgets=None):
+        self.paths = {"joint": joint, "eef": eef}
+        self.budgets = dict(token_budgets or {})
+        if self.budgets.keys() - self.paths.keys():
+            raise ValueError("token_budgets accepts only 'joint' and 'eef'")
+
+    def build(self):
+        processors = {
+            name: ActionCodec2Processor.from_pretrained(path)
+            for name, path in self.paths.items()
+        }
+        budgets = {
+            name: self.budgets.get(
+                name,
+                processor.config.train.bpe.vocab_size
+                if processor.config.train is not None
+                else processor.vocab_size,
+            )
+            for name, processor in processors.items()
+        }
+        return ActionCodec2Router.from_processors(
+            processors,
+            token_budgets=budgets,
+            presets=list(builtin_action_spaces().values()),
+        )
+
+
+_PROFILE_DEFAULTS = {
+    "eef": {
+        "model_type": "actioncodec2_unified",
+        "config_version": 1,
+        "physical": {
+            "input_dim": 7,
+            "components": {
+                "translation_m": {
+                    "dims": {"start": 0, "stop": 3},
+                    "space": "additive",
+                    "input_order": 0,
+                    "primitive_order": 1,
+                    "input_transform": {"scale": 1.0, "clip": False},
+                    "constraints": {
+                        "order_0": {"min": -2.0, "max": 2.0},
+                        "order_1": {"min": -0.08, "max": 0.08},
+                    },
+                    "distortion_limit": 0.005,
+                    "primitive_selection": "smooth",
+                },
+                "orientation_so3": {
+                    "dims": {"start": 3, "stop": 6},
+                    "space": "so3",
+                    "input_order": 0,
+                    "primitive_order": 1,
+                    "input_transform": {"scale": 1.0, "clip": False},
+                    "constraints": {
+                        "order_0": {
+                            "min": -3.141592653589793,
+                            "max": 3.141592653589793,
+                        },
+                        "order_1": {"min": -0.25, "max": 0.25},
+                    },
+                    "distortion_limit": 0.02,
+                    "primitive_selection": "smooth",
+                    "representation": "rotation_vector",
+                    "multiplication": "right",
+                },
+                "gripper_open_command": {
+                    "dims": [6],
+                    "space": "additive",
+                    "input_order": 0,
+                    "primitive_order": 0,
+                    "input_transform": {"scale": 1.0, "clip": True},
+                    "constraints": {"order_0": {"min": 0.0, "max": 1.0}},
+                    "distortion_limit": 0.5,
+                    "primitive_selection": "nearest",
+                },
+            },
+        },
+        "set_bpe": {"lookahead": 8, "allow_cross_component_merge": False},
+        "train": {
+            "primitives": {
+                "zero_primitive_components": ["translation_m", "orientation_so3"]
+            },
+            "bpe": {"spatial_vocab_size": 2048, "vocab_size": 4096},
+            "quality_control": {"hard_order_1_scale": 3.0, "min_segment_length": 2},
+        },
+    },
+    "eef_second_order_pretrain_v2": {
+        "model_type": "actioncodec2_unified",
+        "config_version": 1,
+        "physical": {
+            "input_dim": 7,
+            "components": {
+                "translation_m": {
+                    "dims": {"start": 0, "stop": 3},
+                    "space": "additive",
+                    "input_order": 0,
+                    "primitive_order": 2,
+                    "input_transform": {"scale": 1.0, "clip": False},
+                    "constraints": {
+                        "order_0": {"min": -2.0, "max": 2.0},
+                        "order_2": {"min": -0.025, "max": 0.025},
+                        "order_1": {"min": -0.08, "max": 0.08},
+                    },
+                    "distortion_limit": 0.005,
+                    "primitive_selection": "smooth",
+                },
+                "orientation_so3": {
+                    "dims": {"start": 3, "stop": 6},
+                    "space": "so3",
+                    "input_order": 0,
+                    "primitive_order": 2,
+                    "input_transform": {"scale": 1.0, "clip": False},
+                    "constraints": {
+                        "order_0": {
+                            "min": -3.141592653589793,
+                            "max": 3.141592653589793,
+                        },
+                        "order_2": {"min": -0.08, "max": 0.08},
+                        "order_1": {"min": -0.25, "max": 0.25},
+                    },
+                    "distortion_limit": 0.02,
+                    "primitive_selection": "smooth",
+                    "representation": "rotation_vector",
+                    "multiplication": "right",
+                },
+                "gripper_open_command": {
+                    "dims": [6],
+                    "space": "additive",
+                    "input_order": 0,
+                    "primitive_order": 0,
+                    "input_transform": {"scale": 1.0, "clip": True},
+                    "constraints": {"order_0": {"min": 0.0, "max": 1.0}},
+                    "distortion_limit": 0.5,
+                    "primitive_selection": "nearest",
+                },
+            },
+        },
+        "set_bpe": {"lookahead": 8, "allow_cross_component_merge": False},
+        "train": {
+            "primitives": {
+                "zero_primitive_components": ["translation_m", "orientation_so3"]
+            },
+            "bpe": {"spatial_vocab_size": 2048, "vocab_size": 4096},
+            "quality_control": {"hard_order_1_scale": 3.0, "min_segment_length": 2},
+        },
+    },
+    "joint": {
+        "model_type": "actioncodec2_unified",
+        "config_version": 1,
+        "physical": {
+            "input_dim": 8,
+            "components": {
+                "generalized_joint_position": {
+                    "dims": {"start": 0, "stop": 7},
+                    "space": "additive",
+                    "input_order": 0,
+                    "primitive_order": 1,
+                    "input_transform": {"scale": 1.0, "clip": False},
+                    "constraints": {
+                        "order_0": {
+                            "min": -6.283185307179586,
+                            "max": 6.283185307179586,
+                        },
+                        "order_1": {"min": -0.35, "max": 0.35},
+                    },
+                    "distortion_limit": [
+                        0.004,
+                        0.004,
+                        0.006,
+                        0.0075,
+                        0.015,
+                        0.02,
+                        0.02,
+                    ],
+                    "primitive_selection": "smooth",
+                },
+                "gripper_open_command": {
+                    "dims": [7],
+                    "space": "additive",
+                    "input_order": 0,
+                    "primitive_order": 0,
+                    "input_transform": {"scale": 1.0, "clip": True},
+                    "constraints": {"order_0": {"min": 0.0, "max": 1.0}},
+                    "distortion_limit": 0.5,
+                    "primitive_selection": "nearest",
+                },
+            },
+        },
+        "set_bpe": {"lookahead": 8, "allow_cross_component_merge": False},
+        "train": {
+            "primitives": {"zero_primitive_components": ["generalized_joint_position"]},
+            "bpe": {"spatial_vocab_size": 2048, "vocab_size": 4096},
+            "quality_control": {"hard_order_1_scale": 3.0, "min_segment_length": 2},
+        },
+    },
+    "joint_second_order_pretrain_v2": {
+        "model_type": "actioncodec2_unified",
+        "config_version": 1,
+        "physical": {
+            "input_dim": 8,
+            "components": {
+                "generalized_joint_position": {
+                    "dims": {"start": 0, "stop": 7},
+                    "space": "additive",
+                    "input_order": 0,
+                    "primitive_order": 2,
+                    "input_transform": {"scale": 1.0, "clip": False},
+                    "constraints": {
+                        "order_0": {
+                            "min": -6.283185307179586,
+                            "max": 6.283185307179586,
+                        },
+                        "order_2": {"min": -0.25, "max": 0.25},
+                        "order_1": {"min": -0.35, "max": 0.35},
+                    },
+                    "distortion_limit": [
+                        0.004,
+                        0.004,
+                        0.006,
+                        0.0075,
+                        0.015,
+                        0.02,
+                        0.02,
+                    ],
+                    "primitive_selection": "smooth",
+                },
+                "gripper_open_command": {
+                    "dims": [7],
+                    "space": "additive",
+                    "input_order": 0,
+                    "primitive_order": 0,
+                    "input_transform": {"scale": 1.0, "clip": True},
+                    "constraints": {"order_0": {"min": 0.0, "max": 1.0}},
+                    "distortion_limit": 0.5,
+                    "primitive_selection": "nearest",
+                },
+            },
+        },
+        "set_bpe": {"lookahead": 8, "allow_cross_component_merge": False},
+        "train": {
+            "primitives": {"zero_primitive_components": ["generalized_joint_position"]},
+            "bpe": {"spatial_vocab_size": 2048, "vocab_size": 4096},
+            "quality_control": {"hard_order_1_scale": 3.0, "min_segment_length": 2},
+        },
+    },
+}
+
+_PRESET_DEFAULTS = {
+    "dual_eef_abs": {
+        "name": "dual_eef_abs",
+        "input_dim": 14,
+        "input": "absolute",
+        "source_hz": 15.0,
+        "target_hz": 15.0,
+        "interpolation": "cubic",
+        "components": {
+            "left_arm": {
+                "space": "eef",
+                "position_dims": [0, 1, 2],
+                "rotation_dims": [3, 4, 5],
+                "rotation_format": "rotation_vector",
+                "gripper_dim": 6,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            },
+            "right_arm": {
+                "space": "eef",
+                "position_dims": [7, 8, 9],
+                "rotation_dims": [10, 11, 12],
+                "rotation_format": "rotation_vector",
+                "gripper_dim": 13,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            },
+        },
+    },
+    "dual_eef_delta": {
+        "name": "dual_eef_delta",
+        "input_dim": 14,
+        "input": "delta",
+        "source_hz": 15.0,
+        "target_hz": 15.0,
+        "interpolation": "cubic",
+        "components": {
+            "left_arm": {
+                "space": "eef",
+                "position_dims": [0, 1, 2],
+                "rotation_dims": [3, 4, 5],
+                "rotation_format": "rotation_vector",
+                "gripper_dim": 6,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            },
+            "right_arm": {
+                "space": "eef",
+                "position_dims": [7, 8, 9],
+                "rotation_dims": [10, 11, 12],
+                "rotation_format": "rotation_vector",
+                "gripper_dim": 13,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            },
+        },
+    },
+    "dual_joint6_abs": {
+        "name": "dual_joint6_abs",
+        "input_dim": 14,
+        "input": "absolute",
+        "source_hz": 15.0,
+        "target_hz": 15.0,
+        "interpolation": "cubic",
+        "components": {
+            "left_arm": {
+                "space": "joint",
+                "joint_dims": [0, 1, 2, 3, 4, 5],
+                "gripper_dim": 6,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            },
+            "right_arm": {
+                "space": "joint",
+                "joint_dims": [7, 8, 9, 10, 11, 12],
+                "gripper_dim": 13,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            },
+        },
+    },
+    "dual_joint6_delta": {
+        "name": "dual_joint6_delta",
+        "input_dim": 14,
+        "input": "delta",
+        "source_hz": 15.0,
+        "target_hz": 15.0,
+        "interpolation": "cubic",
+        "components": {
+            "left_arm": {
+                "space": "joint",
+                "joint_dims": [0, 1, 2, 3, 4, 5],
+                "gripper_dim": 6,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            },
+            "right_arm": {
+                "space": "joint",
+                "joint_dims": [7, 8, 9, 10, 11, 12],
+                "gripper_dim": 13,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            },
+        },
+    },
+    "dual_joint7_abs": {
+        "name": "dual_joint7_abs",
+        "input_dim": 16,
+        "input": "absolute",
+        "source_hz": 15.0,
+        "target_hz": 15.0,
+        "interpolation": "cubic",
+        "components": {
+            "left_arm": {
+                "space": "joint",
+                "joint_dims": [0, 1, 2, 3, 4, 5, 6],
+                "gripper_dim": 7,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            },
+            "right_arm": {
+                "space": "joint",
+                "joint_dims": [8, 9, 10, 11, 12, 13, 14],
+                "gripper_dim": 15,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            },
+        },
+    },
+    "dual_joint7_delta": {
+        "name": "dual_joint7_delta",
+        "input_dim": 16,
+        "input": "delta",
+        "source_hz": 15.0,
+        "target_hz": 15.0,
+        "interpolation": "cubic",
+        "components": {
+            "left_arm": {
+                "space": "joint",
+                "joint_dims": [0, 1, 2, 3, 4, 5, 6],
+                "gripper_dim": 7,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            },
+            "right_arm": {
+                "space": "joint",
+                "joint_dims": [8, 9, 10, 11, 12, 13, 14],
+                "gripper_dim": 15,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            },
+        },
+    },
+    "single_eef_abs": {
+        "name": "single_eef_abs",
+        "input_dim": 7,
+        "input": "absolute",
+        "source_hz": 15.0,
+        "target_hz": 15.0,
+        "interpolation": "cubic",
+        "components": {
+            "arm": {
+                "space": "eef",
+                "position_dims": [0, 1, 2],
+                "rotation_dims": [3, 4, 5],
+                "rotation_format": "rotation_vector",
+                "gripper_dim": 6,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            }
+        },
+    },
+    "single_eef_delta": {
+        "name": "single_eef_delta",
+        "input_dim": 7,
+        "input": "delta",
+        "source_hz": 15.0,
+        "target_hz": 15.0,
+        "interpolation": "cubic",
+        "components": {
+            "arm": {
+                "space": "eef",
+                "position_dims": [0, 1, 2],
+                "rotation_dims": [3, 4, 5],
+                "rotation_format": "rotation_vector",
+                "gripper_dim": 6,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            }
+        },
+    },
+    "single_joint6_abs": {
+        "name": "single_joint6_abs",
+        "input_dim": 7,
+        "input": "absolute",
+        "source_hz": 15.0,
+        "target_hz": 15.0,
+        "interpolation": "cubic",
+        "components": {
+            "arm": {
+                "space": "joint",
+                "joint_dims": [0, 1, 2, 3, 4, 5],
+                "gripper_dim": 6,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            }
+        },
+    },
+    "single_joint6_abs_continuous_gripper": {
+        "name": "single_joint6_abs_continuous_gripper",
+        "input_dim": 6,
+        "input": "absolute",
+        "source_hz": 15.0,
+        "target_hz": 15.0,
+        "interpolation": "cubic",
+        "components": {"arm": {"space": "joint", "joint_dims": [0, 1, 2, 3, 4, 5]}},
+    },
+    "single_joint6_delta": {
+        "name": "single_joint6_delta",
+        "input_dim": 7,
+        "input": "delta",
+        "source_hz": 15.0,
+        "target_hz": 15.0,
+        "interpolation": "cubic",
+        "components": {
+            "arm": {
+                "space": "joint",
+                "joint_dims": [0, 1, 2, 3, 4, 5],
+                "gripper_dim": 6,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            }
+        },
+    },
+    "single_joint7_abs": {
+        "name": "single_joint7_abs",
+        "input_dim": 8,
+        "input": "absolute",
+        "source_hz": 15.0,
+        "target_hz": 15.0,
+        "interpolation": "cubic",
+        "components": {
+            "arm": {
+                "space": "joint",
+                "joint_dims": [0, 1, 2, 3, 4, 5, 6],
+                "gripper_dim": 7,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            }
+        },
+    },
+    "single_joint7_delta": {
+        "name": "single_joint7_delta",
+        "input_dim": 8,
+        "input": "delta",
+        "source_hz": 15.0,
+        "target_hz": 15.0,
+        "interpolation": "cubic",
+        "components": {
+            "arm": {
+                "space": "joint",
+                "joint_dims": [0, 1, 2, 3, 4, 5, 6],
+                "gripper_dim": 7,
+                "gripper_threshold": 0.8,
+                "gripper_open_is_high": True,
+            }
+        },
+    },
+}

runtime/routing/presets.py

@@ -0,0 +1,802 @@
+"""User-facing action layouts compiled into shared joint/EEF trajectories."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import yaml
+
+from ..common._validation import optional_finite_array, validate_dimension_partition
+from ..physical.configuration import (
+    ConfigError,
+    _integer,
+    _mapping,
+    _number,
+    _reject_unknown,
+    _required,
+    _UniqueKeyLoader,
+)
+from ..physical.semantic import (
+    binarize_gripper_actions,
+    eef_pose_absolute,
+    eef_pose_components,
+    eef_pose_deltas,
+    eef_pose_from_components,
+    eef_pose_from_local_absolute,
+    eef_pose_local_absolute,
+    integrate_eef_deltas,
+    resample_uniform,
+)
+from ..physical.trajectory import ActiveTrajectory
+
+_NAME = re.compile(r"[a-z][a-z0-9_]*\Z")
+_SPACES = {"eef", "joint"}
+_INPUTS = {"absolute", "delta"}
+_ROTATIONS = {"rotation_vector", "euler_xyz", "quaternion_xyzw"}
+_INTERPOLATIONS = {"linear", "pchip", "cubic"}
+_GRIPPER_DIM = {"eef": 6, "joint": 7}
+
+
+def _format_dims(dims: Sequence[int]) -> str:
+    values = tuple(dims)
+    if len(values) == 1:
+        return str(values[0])
+    if values == tuple(range(values[0], values[-1] + 1)):
+        return f"{values[0]}..{values[-1]}"
+    return ",".join(map(str, values))
+
+
+def _dims(value: object, path: str) -> tuple[int, ...]:
+    if not isinstance(value, Sequence) or isinstance(value, (str, bytes, bytearray)):
+        raise ConfigError(f"{path} must be a list of dimensions")
+    output = tuple(
+        _integer(item, f"{path}[{index}]") for index, item in enumerate(value)
+    )
+    if not output:
+        raise ConfigError(f"{path} must not be empty")
+    if len(set(output)) != len(output):
+        raise ConfigError(f"{path} contains a repeated dimension")
+    return output
+
+
+@dataclass(frozen=True)
+class ComponentSpec:
+    "One independently encoded arm/body component in an input tensor."
+
+    name: str
+    space: str
+    joint_dims: tuple[int, ...] | None = None
+    position_dims: tuple[int, ...] | None = None
+    rotation_dims: tuple[int, ...] | None = None
+    rotation_format: str = "rotation_vector"
+    gripper_dim: int | None = None
+    gripper_threshold: float | None = None
+    gripper_open_is_high: bool = True
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.name, str) or _NAME.fullmatch(self.name) is None:
+            raise ConfigError(f"component name must match {_NAME.pattern!r}")
+        if self.space not in _SPACES:
+            raise ConfigError(f"component {self.name!r}.space must be joint or eef")
+        if self.rotation_format not in _ROTATIONS:
+            raise ConfigError(
+                f"component {self.name!r}.rotation_format must be one of {sorted(_ROTATIONS)}"
+            )
+        for label, dims in (
+            ("joint_dims", self.joint_dims),
+            ("position_dims", self.position_dims),
+            ("rotation_dims", self.rotation_dims),
+        ):
+            if dims is not None:
+                _dims(dims, f"component {self.name}.{label}")
+        self._validate_motion_dims()
+        raw_dims = self.source_dims
+        if self.gripper_dim is not None:
+            _integer(self.gripper_dim, f"component {self.name}.gripper_dim")
+            if self.gripper_dim in raw_dims:
+                raise ConfigError(
+                    f"component {self.name!r}.gripper_dim overlaps motion dims"
+                )
+        if not isinstance(self.gripper_open_is_high, bool):
+            raise ConfigError(
+                f"component {self.name!r}.gripper_open_is_high must be boolean"
+            )
+        threshold = self.gripper_threshold
+        if threshold is None:
+            threshold = 0.8 if self.gripper_open_is_high else 0.2
+            object.__setattr__(self, "gripper_threshold", threshold)
+        _number(threshold, f"component {self.name}.gripper_threshold")
+
+    def _validate_motion_dims(self) -> None:
+        if self.space == "joint":
+            if self.joint_dims is None or not 1 <= len(self.joint_dims) <= 7:
+                raise ConfigError(
+                    f"joint component {self.name!r} requires 1..7 joint_dims"
+                )
+            if self.position_dims is not None or self.rotation_dims is not None:
+                raise ConfigError(
+                    f"joint component {self.name!r} cannot define EEF dims"
+                )
+            return
+        if self.joint_dims is not None:
+            raise ConfigError(f"EEF component {self.name!r} cannot define joint_dims")
+        if self.position_dims is None or len(self.position_dims) != 3:
+            raise ConfigError(
+                f"EEF component {self.name!r} requires three position_dims"
+            )
+        expected = 4 if self.rotation_format == "quaternion_xyzw" else 3
+        if self.rotation_dims is None or len(self.rotation_dims) != expected:
+            raise ConfigError(
+                f"EEF component {self.name!r} requires {expected} rotation_dims for "
+                f"{self.rotation_format}"
+            )
+        if set(self.position_dims).intersection(self.rotation_dims):
+            raise ConfigError(f"EEF component {self.name!r} reuses a pose dimension")
+
+    @property
+    def source_dims(self) -> tuple[int, ...]:
+        """All source motion columns in canonical component order."""
+        if self.space == "joint":
+            assert self.joint_dims is not None
+            return self.joint_dims
+        assert self.position_dims is not None and self.rotation_dims is not None
+        return (*self.position_dims, *self.rotation_dims)
+
+    @property
+    def all_source_dims(self) -> tuple[int, ...]:
+        """Motion plus optional binary-gripper source columns."""
+        return (
+            self.source_dims
+            if self.gripper_dim is None
+            else (*self.source_dims, self.gripper_dim)
+        )
+
+    @property
+    def active_dims(self) -> tuple[int, ...]:
+        """Shared-profile slots emitted by this component."""
+        motion_width = len(self.joint_dims or ()) if self.space == "joint" else 6
+        dims = tuple(range(motion_width))
+        return dims if self.gripper_dim is None else (*dims, _GRIPPER_DIM[self.space])
+
+    @classmethod
+    def from_dict(cls, name: str, payload: object, *, path: str) -> ComponentSpec:
+        values = _mapping(payload, path)
+        allowed = {
+            "space",
+            "joint_dims",
+            "position_dims",
+            "rotation_dims",
+            "rotation_format",
+            "gripper_dim",
+            "gripper_threshold",
+            "gripper_open_is_high",
+        }
+        _reject_unknown(values, allowed, path)
+        gripper_dim = values.get("gripper_dim")
+        if gripper_dim is not None:
+            gripper_dim = _integer(gripper_dim, f"{path}.gripper_dim")
+        return cls(
+            name=name,
+            space=str(_required(values, "space", path)),
+            joint_dims=None
+            if "joint_dims" not in values
+            else _dims(values["joint_dims"], f"{path}.joint_dims"),
+            position_dims=None
+            if "position_dims" not in values
+            else _dims(values["position_dims"], f"{path}.position_dims"),
+            rotation_dims=None
+            if "rotation_dims" not in values
+            else _dims(values["rotation_dims"], f"{path}.rotation_dims"),
+            rotation_format=str(values.get("rotation_format", "rotation_vector")),
+            gripper_dim=gripper_dim,
+            gripper_threshold=(
+                None
+                if values.get("gripper_threshold") is None
+                else _number(values["gripper_threshold"], f"{path}.gripper_threshold")
+            ),
+            gripper_open_is_high=values.get("gripper_open_is_high", True),
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        payload: dict[str, object] = {"space": self.space}
+        if self.space == "joint":
+            payload["joint_dims"] = list(self.joint_dims or ())
+        else:
+            payload.update(
+                {
+                    "position_dims": list(self.position_dims or ()),
+                    "rotation_dims": list(self.rotation_dims or ()),
+                    "rotation_format": self.rotation_format,
+                }
+            )
+        if self.gripper_dim is not None:
+            payload.update(
+                {
+                    "gripper_dim": self.gripper_dim,
+                    "gripper_threshold": self.gripper_threshold,
+                    "gripper_open_is_high": self.gripper_open_is_high,
+                }
+            )
+        return payload
+
+
+@dataclass(frozen=True)
+class PresetConfig:
+    "A dataset- and embodiment-independent physical ``[B,T,D]`` contract."
+
+    name: str
+    input_dim: int
+    input: str
+    components: tuple[ComponentSpec, ...]
+    source_hz: float = 15.0
+    target_hz: float = 15.0
+    interpolation: str = "cubic"
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.name, str) or _NAME.fullmatch(self.name) is None:
+            raise ConfigError(f"preset.name must match {_NAME.pattern!r}")
+        _integer(self.input_dim, "preset.input_dim", positive=True)
+        if self.input not in _INPUTS:
+            raise ConfigError("preset.input must be absolute or delta")
+        if not self.components:
+            raise ConfigError("preset.components must not be empty")
+        if not all(
+            isinstance(component, ComponentSpec) for component in self.components
+        ):
+            raise ConfigError("preset.components must contain ComponentSpec values")
+        names = [component.name for component in self.components]
+        if len(set(names)) != len(names):
+            raise ConfigError("preset.components contains a duplicate name")
+        self._validate_source_partition()
+        for rate, path in (
+            (self.source_hz, "source_hz"),
+            (self.target_hz, "target_hz"),
+        ):
+            checked = _number(rate, f"preset.{path}")
+            if checked <= 0.0:
+                raise ConfigError(f"preset.{path} must be positive and finite")
+        if self.interpolation not in _INTERPOLATIONS:
+            raise ConfigError(
+                f"preset.interpolation must be one of {sorted(_INTERPOLATIONS)}"
+            )
+        if self.input == "delta" and any(
+            component.space == "eef" and component.rotation_format != "rotation_vector"
+            for component in self.components
+        ):
+            raise ConfigError(
+                "EEF delta components require rotation_format=rotation_vector"
+            )
+
+    def _validate_source_partition(self) -> None:
+        validate_dimension_partition(
+            (
+                (component.name, component.all_source_dims)
+                for component in self.components
+            ),
+            self.input_dim,
+            label="input dim",
+            error_type=ConfigError,
+        )
+
+    @classmethod
+    def from_dict(cls, payload: object, *, path: str = "preset") -> PresetConfig:
+        values = _mapping(payload, path)
+        allowed = {
+            "name",
+            "input_dim",
+            "input",
+            "source_hz",
+            "target_hz",
+            "interpolation",
+            "components",
+        }
+        _reject_unknown(values, allowed, path)
+        raw_components = _mapping(
+            _required(values, "components", path), f"{path}.components"
+        )
+        components = tuple(
+            ComponentSpec.from_dict(name, raw, path=f"{path}.components.{name}")
+            for name, raw in raw_components.items()
+        )
+        return cls(
+            name=str(_required(values, "name", path)),
+            input_dim=_integer(
+                _required(values, "input_dim", path), f"{path}.input_dim", positive=True
+            ),
+            input=str(_required(values, "input", path)),
+            components=components,
+            source_hz=_number(values.get("source_hz", 15.0), f"{path}.source_hz"),
+            target_hz=_number(values.get("target_hz", 15.0), f"{path}.target_hz"),
+            interpolation=str(values.get("interpolation", "cubic")),
+        )
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> PresetConfig:
+        """Load one strict user preset without executing arbitrary code."""
+        source = Path(path)
+        try:
+            payload = yaml.load(
+                source.read_text(encoding="utf-8"), Loader=_UniqueKeyLoader
+            )
+        except yaml.YAMLError as error:
+            raise ConfigError(f"cannot parse {source}: {error}") from error
+        return cls.from_dict(payload, path=str(source))
+
+    def save_yaml(self, path: str | Path) -> Path:
+        """Save the complete reproducible preset and return its path."""
+        target = Path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(
+            yaml.safe_dump(self.to_dict(), sort_keys=False), encoding="utf-8"
+        )
+        return target
+
+    def to_dict(self) -> dict[str, object]:
+        payload = {
+            "name": self.name,
+            "input_dim": self.input_dim,
+            "input": self.input,
+            "source_hz": self.source_hz,
+            "target_hz": self.target_hz,
+            "interpolation": self.interpolation,
+            "components": {
+                component.name: component.to_dict() for component in self.components
+            },
+        }
+        return payload
+
+    def summary(self) -> str:
+        """Return a compact action-space label for discovery UIs."""
+        spaces = "+".join(
+            dict.fromkeys(component.space for component in self.components)
+        )
+        return f"{self.name} (D={self.input_dim}, {self.input}, {spaces}, {self.source_hz:g} Hz input)"
+
+    def describe(self) -> str:
+        """Describe every source tensor column and its physical interpretation."""
+        motion = "position" if self.input == "absolute" else "per-step delta"
+        lines = [self.summary()]
+        for component in self.components:
+            if component.space == "joint":
+                assert component.joint_dims is not None
+                lines.append(
+                    f"  dims {_format_dims(component.joint_dims)}: {component.name} "
+                    f"generalized-joint {motion} [rad or registered canonical unit]"
+                )
+            else:
+                assert component.position_dims is not None
+                assert component.rotation_dims is not None
+                lines.append(
+                    f"  dims {_format_dims(component.position_dims)}: {component.name} "
+                    f"EEF translation {motion} (x, y, z in listed order) [m]"
+                )
+                rotation_motion = (
+                    "orientation" if self.input == "absolute" else "increment"
+                )
+                rotation_unit = (
+                    "unit xyzw quaternion"
+                    if component.rotation_format == "quaternion_xyzw"
+                    else "rad"
+                )
+                lines.append(
+                    f"  dims {_format_dims(component.rotation_dims)}: {component.name} EEF "
+                    f"{rotation_motion} [{component.rotation_format}, {rotation_unit}]"
+                )
+                if self.input == "delta":
+                    lines.append(
+                        "    rotation_vector = axis * angle [rad], right-multiplicative "
+                        "body-frame increment: R_next = R_previous @ Exp(rotvec)"
+                    )
+                elif component.rotation_format == "rotation_vector":
+                    lines.append(
+                        "    rotation_vector = axis * angle [rad], not Euler angles"
+                    )
+                elif component.rotation_format == "euler_xyz":
+                    lines.append("    euler_xyz = extrinsic x, y, z Euler angles [rad]")
+            if component.gripper_dim is not None:
+                comparison = ">=" if component.gripper_open_is_high else "<="
+                lines.append(
+                    f"  dim {component.gripper_dim}: {component.name} gripper command "
+                    f"(open if value {comparison} {component.gripper_threshold:g}, otherwise closed; "
+                    "decoded as absolute command: 1=open, 0=closed)"
+                )
+            else:
+                lines.append(
+                    f"  {component.name}: no binary gripper channel; all listed columns are motion"
+                )
+        if self.input == "absolute":
+            lines.append(
+                "  encode/decode require the same current_state (B,D), immediately before row 0"
+            )
+        else:
+            lines.append(
+                "  encode/decode: omit current_state; deltas are per-step increments, not velocities"
+            )
+        lines.append(
+            f"  resampling: {self.source_hz:g} Hz default -> {self.target_hz:g} Hz codec "
+            f"clock ({self.interpolation})"
+        )
+        return "\n".join(lines)
+
+    def canonicalize(
+        self,
+        values: np.ndarray,
+        *,
+        source_hz: float | None = None,
+        current_state: np.ndarray | None = None,
+    ) -> dict[str, list[ActiveTrajectory]]:
+        "Convert a batch into local paths for the two shared profiles."
+        array = np.asarray(values, dtype=np.float32)
+        if array.ndim != 3 or len(array) < 1 or array.shape[1] < 1:
+            raise ValueError("preset input must have non-empty shape [B, T, D]")
+        if array.shape[2] != self.input_dim:
+            raise ValueError(
+                f"preset {self.name!r} expects input_dim={self.input_dim}, got {array.shape[2]}"
+            )
+        if not np.all(np.isfinite(array)):
+            raise ValueError("preset input contains a non-finite value")
+        states: list[np.ndarray | None]
+        if current_state is None:
+            states = [None] * len(array)
+        else:
+            state_array = optional_finite_array(
+                current_state, shape=(len(array), self.input_dim)
+            )
+            assert state_array is not None
+            states = list(state_array)
+        return {
+            component.name: [
+                self._canonicalize_component(
+                    episode,
+                    component,
+                    source_hz=self.source_hz if source_hz is None else source_hz,
+                    current_state=state,
+                )
+                for episode, state in zip(array, states, strict=True)
+            ]
+            for component in self.components
+        }
+
+    def canonicalize_episode(
+        self,
+        values: np.ndarray,
+        *,
+        source_hz: float | None = None,
+        current_state: np.ndarray | None = None,
+    ) -> dict[str, ActiveTrajectory]:
+        """Canonicalize one variable-length episode and optional ``(D,)`` anchor."""
+        episode = np.asarray(values, dtype=np.float32)
+        if episode.ndim != 2 or len(episode) < 1 or episode.shape[1] != self.input_dim:
+            raise ValueError(
+                f"preset {self.name!r} expects a non-empty [T, {self.input_dim}] episode"
+            )
+        if not np.all(np.isfinite(episode)):
+            raise ValueError("preset input contains a non-finite value")
+        state = optional_finite_array(current_state, shape=(self.input_dim,))
+        return {
+            component.name: self._canonicalize_component(
+                episode,
+                component,
+                source_hz=self.source_hz if source_hz is None else source_hz,
+                current_state=state,
+            )
+            for component in self.components
+        }
+
+    def profile_trajectories(
+        self, values: np.ndarray, *, current_state: np.ndarray | None = None
+    ) -> dict[str, list[ActiveTrajectory]]:
+        """Canonicalize one episode and group its components by joint/EEF profile."""
+        canonical = self.canonicalize_episode(values, current_state=current_state)
+        output: dict[str, list[ActiveTrajectory]] = {}
+        for component in self.components:
+            output.setdefault(component.space, []).append(canonical[component.name])
+        return output
+
+    def _canonicalize_component(
+        self,
+        episode: np.ndarray,
+        component: ComponentSpec,
+        *,
+        source_hz: float,
+        current_state: np.ndarray | None,
+    ) -> ActiveTrajectory:
+        if component.space == "joint":
+            motion = self._joint_motion(
+                episode, component, source_hz=source_hz, current_state=current_state
+            )
+        else:
+            motion = self._eef_motion(
+                episode, component, source_hz=source_hz, current_state=current_state
+            )
+        if component.gripper_dim is None:
+            return ActiveTrajectory(motion, component.active_dims)
+        gripper = resample_uniform(
+            episode[:, component.gripper_dim : component.gripper_dim + 1],
+            source_hz=source_hz,
+            target_hz=self.target_hz,
+            kind="hold",
+            method=self.interpolation,
+        )
+        binary = binarize_gripper_actions(
+            gripper,
+            threshold=component.gripper_threshold,
+            open_is_high=component.gripper_open_is_high,
+        )
+        if len(binary) != len(motion):
+            raise RuntimeError("motion and gripper produced different target horizons")
+        return ActiveTrajectory(
+            np.concatenate((motion, binary), axis=1), component.active_dims
+        )
+
+    def _joint_motion(
+        self,
+        episode: np.ndarray,
+        component: ComponentSpec,
+        *,
+        source_hz: float,
+        current_state: np.ndarray | None,
+    ) -> np.ndarray:
+        assert component.joint_dims is not None
+        source = np.take(episode, component.joint_dims, axis=1)
+        if self.input == "delta":
+            source = np.cumsum(source, axis=0, dtype=np.float32)
+            anchor = np.zeros((1, source.shape[1]), dtype=np.float32)
+        else:
+            raw_anchor = (
+                source[:1]
+                if current_state is None
+                else np.take(current_state, component.joint_dims)[None]
+            )
+            unwrapped = np.unwrap(np.concatenate((raw_anchor, source), axis=0), axis=0)
+            anchor = np.asarray(unwrapped[:1], dtype=np.float32)
+            source = np.asarray(unwrapped[1:], dtype=np.float32)
+        sampled = resample_uniform(
+            source,
+            source_hz=source_hz,
+            target_hz=self.target_hz,
+            kind="linear",
+            method=self.interpolation,
+        )
+        return np.asarray(sampled - anchor, dtype=np.float32)
+
+    def _eef_motion(
+        self,
+        episode: np.ndarray,
+        component: ComponentSpec,
+        *,
+        source_hz: float,
+        current_state: np.ndarray | None,
+    ) -> np.ndarray:
+        assert (
+            component.position_dims is not None and component.rotation_dims is not None
+        )
+        position = np.take(episode, component.position_dims, axis=1)
+        rotation = np.take(episode, component.rotation_dims, axis=1)
+        if self.input == "delta":
+            pose = integrate_eef_deltas(np.concatenate((position, rotation), axis=1))
+            pose = resample_uniform(
+                pose,
+                source_hz=source_hz,
+                target_hz=self.target_hz,
+                kind="pose_xyzw",
+                method=self.interpolation,
+            )
+            return eef_pose_absolute(pose)
+        pose = eef_pose_from_components(position, rotation, component.rotation_format)
+        if current_state is None:
+            initial_pose = pose[0]
+        else:
+            initial_pose = eef_pose_from_components(
+                np.take(current_state, component.position_dims)[None],
+                np.take(current_state, component.rotation_dims)[None],
+                component.rotation_format,
+            )[0]
+        pose = resample_uniform(
+            pose,
+            source_hz=source_hz,
+            target_hz=self.target_hz,
+            kind="pose_xyzw",
+            method=self.interpolation,
+        )
+        return eef_pose_local_absolute(pose, initial_pose=initial_pose)
+
+
+def format_action_spaces(
+    presets: Mapping[str, PresetConfig],
+    *,
+    selected: str | None = None,
+    action_dim: int | None = None,
+    second_order_dims: Mapping[str, Sequence[int]] | None = None,
+) -> str:
+    "Explain registered tensor layouts without inferring semantics from shape."
+    if action_dim is not None:
+        action_dim = _integer(action_dim, "action_dim", positive=True)
+    if not presets:
+        return "No action spaces are registered."
+    candidates = sorted(
+        (
+            preset
+            for preset in presets.values()
+            if action_dim is None or preset.input_dim == action_dim
+        ),
+        key=lambda preset: (preset.input_dim, preset.name),
+    )
+    lines = [
+        "ActionCodec2 — action layout guide",
+        f"Selected action_space: {selected or 'none (choose a layout before encoding)'}",
+        "",
+        "Input: NumPy arrays or Torch tensors, (T,D) or (B,T,D).",
+        "  T = timesteps, D = columns per action, B = batch size; column indices start at 0.",
+        "  Any positive T is accepted. A batch needs equal T; encode unequal-length episodes separately.",
+        "  decode returns (B,T,D), including B=1 for a single episode; values are quantized, not lossless.",
+        "",
+        "How to choose:",
+        "  joint = robot joint coordinates; EEF = end-effector (tool) position and orientation.",
+        "  absolute = target coordinates; delta = per-step motion increments, not velocities.",
+        "  Match column order, units, rotation convention, gripper commands and controller fps.",
+        "  Shape alone cannot identify physical meaning: layouts sharing D are only candidates.",
+        "  Consult your dataset/controller documentation if these meanings are unknown.",
+        "  Supply physical units, not normalized [-1,1] features; convert degrees to radians.",
+        "  Non-radian joint coordinates need an explicit mapping to the registered canonical units.",
+        "  Pass the actual sampling rate as fps=...; defaults and codec rates appear below.",
+        "  Resampling can change decoded T; token coverage determines the returned length.",
+        "",
+        f"Registered configurations: {len(candidates)} shown / {len(presets)} total"
+        + (
+            ""
+            if action_dim is None
+            else f" (D={action_dim} candidates, not automatic selection)"
+        ),
+    ]
+    if not candidates:
+        widths = ", ".join(
+            map(str, sorted({preset.input_dim for preset in presets.values()}))
+        )
+        lines.extend(
+            [
+                f"  No registered action space matches D={action_dim}. Available D: {widths}.",
+                "  Confirm your column meanings and register a custom layout; do not pad/truncate to force a match.",
+            ]
+        )
+    for preset in candidates:
+        name = preset.name
+        marker = " [selected]" if name == selected else ""
+        description = preset.describe().splitlines()
+        lines.extend(["", f"- {description[0]}{marker}"])
+        lines.extend(f"  {line.strip()}" for line in description[1:])
+        if second_order_dims is not None:
+            boundaries = [
+                f"{component.name!r}: (B,{len(component.active_dims)})"
+                for component in preset.components
+                if set(component.active_dims).intersection(
+                    second_order_dims.get(component.space, ())
+                )
+            ]
+            lines.append(
+                "  previous_first_order: "
+                + (
+                    "required in encode/decode, {" + ", ".join(boundaries) + "}; "
+                    f"reconstructed increments at {preset.target_hz:g} Hz, B=1 for a single episode"
+                    if boundaries
+                    else "not required by this artifact for this layout"
+                )
+            )
+    lines.extend(
+        [
+            "",
+            "Next steps:",
+            "  Load:   ActionCodec2.from_pretrained(path, action_space='NAME')",
+            "  Switch: codec = codec.for_action_space('NAME')",
+            "  Filter: codec.print_action_spaces(action_dim=D)",
+            "  Config: codec.action_spaces['NAME'].to_dict()  # exact settings for a listed layout",
+            "  Custom: codec.register_action_space(preset)  # explicit column definitions, then switch",
+            "  Custom layouts can reorder columns; each joint component supports 1..7 coordinates.",
+            "  EEF absolute rotations support rotation_vector, euler_xyz or quaternion_xyzw (unit x,y,z,w).",
+            "  EEF delta rotations require rotation_vector with the convention shown above.",
+            "  For absolute layouts, current_state is (B,D), even when actions are (T,D).",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def resample_canonical_trajectory(
+    trajectory: ActiveTrajectory,
+    component: ComponentSpec,
+    *,
+    source_hz: float,
+    target_hz: float,
+    target_length: int | None = None,
+    method: str = "linear",
+) -> ActiveTrajectory:
+    """Rate-convert one decoded canonical component without changing slots."""
+    values = np.asarray(trajectory.values, dtype=np.float32)
+    motion_width = len(component.joint_dims or ()) if component.space == "joint" else 6
+    motion = values[:, :motion_width]
+    if component.space == "eef":
+        pose = eef_pose_from_components(
+            motion[:, :3], motion[:, 3:6], "rotation_vector"
+        )
+        sampled_pose = resample_uniform(
+            pose,
+            source_hz=source_hz,
+            target_hz=target_hz,
+            kind="pose_xyzw",
+            target_length=target_length,
+            method=method,
+        )
+        sampled_motion = eef_pose_absolute(sampled_pose)
+    else:
+        sampled_motion = resample_uniform(
+            motion,
+            source_hz=source_hz,
+            target_hz=target_hz,
+            kind="linear",
+            target_length=target_length,
+            method=method,
+        )
+    if component.gripper_dim is None:
+        return ActiveTrajectory(sampled_motion, trajectory.active_dims)
+    gripper = resample_uniform(
+        values[:, motion_width : motion_width + 1],
+        source_hz=source_hz,
+        target_hz=target_hz,
+        kind="hold",
+        target_length=target_length,
+        method=method,
+    )
+    return ActiveTrajectory(
+        np.concatenate((sampled_motion, gripper), axis=1), trajectory.active_dims
+    )
+
+
+def externalize_canonical_trajectory(
+    trajectory: ActiveTrajectory,
+    component: ComponentSpec,
+    *,
+    current_state: np.ndarray | None,
+) -> np.ndarray:
+    "Return deltas, or absolute values when an external anchor is supplied."
+    values = np.asarray(trajectory.values, dtype=np.float32)
+    motion_width = len(component.joint_dims or ()) if component.space == "joint" else 6
+    motion = values[:, :motion_width]
+    if component.space == "joint":
+        if current_state is None:
+            previous = np.concatenate((np.zeros_like(motion[:1]), motion[:-1]), axis=0)
+            output_motion = motion - previous
+        else:
+            assert component.joint_dims is not None
+            output_motion = motion + np.take(current_state, component.joint_dims)[None]
+    else:
+        local_pose = eef_pose_from_components(
+            motion[:, :3], motion[:, 3:6], "rotation_vector"
+        )
+        if current_state is None:
+            output_motion = eef_pose_deltas(local_pose)
+        else:
+            assert (
+                component.position_dims is not None
+                and component.rotation_dims is not None
+            )
+            initial_pose = eef_pose_from_components(
+                np.take(current_state, component.position_dims)[None],
+                np.take(current_state, component.rotation_dims)[None],
+                component.rotation_format,
+            )[0]
+            output_motion = eef_pose_components(
+                eef_pose_from_local_absolute(local_pose, initial_pose=initial_pose),
+                component.rotation_format,
+            )
+    if component.gripper_dim is None:
+        return np.asarray(output_motion, dtype=np.float32)
+    gripper = values[:, motion_width : motion_width + 1]
+    if not component.gripper_open_is_high:
+        gripper = 1.0 - gripper
+    return np.asarray(
+        np.concatenate((output_motion, gripper), axis=1),
+        dtype=np.float32,
+    )

runtime/routing/routing.py

@@ -0,0 +1,745 @@
+"Required-preset routing over the two shared ActionCodec2 processors."
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from types import MappingProxyType
+from typing import TYPE_CHECKING
+
+import numpy as np
+import yaml
+
+from ..common._validation import optional_finite_array
+from .cache import BoundedCache
+from ..physical.configuration import (
+    ConfigError,
+    _integer,
+    _mapping,
+    _reject_unknown,
+    _required,
+    _UniqueKeyLoader,
+)
+from ..integration.hf import (
+    ROUTER_ALLOW_PATTERNS,
+    ROUTER_CONFIG_NAME,
+    ROUTER_MODEL_TYPE,
+    resolve_pretrained_directory,
+    save_huggingface_metadata,
+    save_model_card,
+)
+from ..physical.physical_processor import ActionCodec2Processor
+from .presets import (
+    ComponentSpec,
+    PresetConfig,
+    externalize_canonical_trajectory,
+    format_action_spaces,
+    resample_canonical_trajectory,
+)
+from ..physical.semantic import resampled_horizon
+from ..physical.trajectory import ActiveTrajectory
+
+if TYPE_CHECKING:
+    from .processing_actioncodec2 import ActionCodec2
+
+
+ROUTER_CONFIG_VERSION = 3
+_NAME = re.compile(r"[a-z][a-z0-9_]*\Z")
+_PROFILES = {"eef", "joint"}
+_PROFILE_WIDTHS = {"eef": 7, "joint": 8}
+
+
+def _current_state_rows(
+    current_state: np.ndarray | None, *, count: int, input_dim: int
+) -> list[np.ndarray | None]:
+    if current_state is None:
+        return [None] * count
+    values = optional_finite_array(current_state, shape=(count, input_dim))
+    assert values is not None
+    return list(values)
+
+
+@dataclass(frozen=True)
+class ProfileSpec:
+    """Token namespace metadata for one shared physical processor."""
+
+    name: str
+    token_offset: int
+    token_budget: int
+    artifact_fingerprint: str
+
+    def __post_init__(self) -> None:
+        if _NAME.fullmatch(self.name) is None:
+            raise ConfigError(f"profile.name must match {_NAME.pattern!r}")
+        _integer(self.token_offset, "profile.token_offset")
+        _integer(self.token_budget, "profile.token_budget", positive=True)
+        if re.fullmatch(r"[0-9a-f]{64}", self.artifact_fingerprint) is None:
+            raise ConfigError(
+                "profile.artifact_fingerprint must be a SHA-256 hex digest"
+            )
+
+    @classmethod
+    def from_dict(cls, payload: object, *, path: str) -> ProfileSpec:
+        values = _mapping(payload, path)
+        allowed = {"name", "token_offset", "token_budget", "artifact_fingerprint"}
+        _reject_unknown(values, allowed, path)
+        return cls(
+            name=str(_required(values, "name", path)),
+            token_offset=_integer(
+                _required(values, "token_offset", path), f"{path}.token_offset"
+            ),
+            token_budget=_integer(
+                _required(values, "token_budget", path),
+                f"{path}.token_budget",
+                positive=True,
+            ),
+            artifact_fingerprint=str(_required(values, "artifact_fingerprint", path)),
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class _ProfileRuntime:
+    spec: ProfileSpec
+    processor: ActionCodec2Processor
+
+
+@dataclass(frozen=True)
+class _Segment:
+    component: ComponentSpec
+    profile: _ProfileRuntime
+
+
+class RoutedActionCodec2Grammar:
+    """Constrained grammar over a preset's ordered, namespaced segments."""
+
+    def __init__(
+        self, router: ActionCodec2Router, *, preset: str, horizon: int
+    ) -> None:
+        horizon = _integer(horizon, "horizon", positive=True)
+        self.segments = router._segments(router.preset(preset))
+        self.vocab_size = router.vocab_size
+        self._grammars = tuple(
+            segment.profile.processor.grammar(
+                horizon, active_dims=segment.component.active_dims
+            )
+            for segment in self.segments
+        )
+        initial = self._normalize_state(0, self._grammars[0]._initial_state())
+        self._initial_state = initial
+        self._state_cache = BoundedCache(256)
+        self._state_cache[()] = initial
+
+    def _normalize_state(
+        self, segment_index: int, state: tuple[int, ...]
+    ) -> tuple[int, tuple[int, ...]]:
+        while segment_index < len(self.segments) and self._grammars[
+            segment_index
+        ]._state_is_complete(state):
+            segment_index += 1
+            if segment_index < len(self.segments):
+                state = self._grammars[segment_index]._initial_state()
+        return segment_index, state
+
+    def _advance_routed_state(
+        self,
+        routed_state: tuple[int, tuple[int, ...]],
+        token: int,
+    ) -> tuple[int, tuple[int, ...]] | None:
+        segment_index, state = routed_state
+        if segment_index == len(self.segments):
+            return None
+        segment = self.segments[segment_index]
+        local_token = token - segment.profile.spec.token_offset
+        if not 0 <= local_token < segment.profile.processor.vocab_size:
+            return None
+        next_state = self._grammars[segment_index]._advance(state, local_token)
+        if next_state is None:
+            return None
+        return self._normalize_state(segment_index, next_state)
+
+    def _consume(self, tokens: Sequence[int]) -> tuple[int, tuple[int, ...]] | None:
+        checked: list[int] = []
+        for raw_token in tokens:
+            if isinstance(raw_token, bool) or not isinstance(
+                raw_token, (int, np.integer)
+            ):
+                return None
+            checked.append(int(raw_token))
+        key = tuple(checked)
+        if not key:
+            return self._initial_state
+        missing = object()
+        cached = self._state_cache.get(key, missing)
+        if cached is not missing:
+            return cached
+        parent = key[:-1]
+        state = self._state_cache.get(parent, missing)
+        if state is missing:
+            state = self._initial_state
+            for token in parent:
+                if state is None:
+                    break
+                state = self._advance_routed_state(state, token)
+            self._state_cache[parent] = state
+        if state is not None:
+            state = self._advance_routed_state(state, key[-1])
+        self._state_cache[key] = state
+        return state
+
+    def next_token_mask(self, tokens: Sequence[int]) -> np.ndarray:
+        """Return a global namespace mask for the next preset token."""
+        state = self._consume(tokens)
+        if state is None:
+            raise ValueError("token prefix is not legal for this routed preset")
+        segment_index, local_state = state
+        output = np.zeros(self.vocab_size, dtype=bool)
+        if segment_index == len(self.segments):
+            return output
+        segment = self.segments[segment_index]
+        mask = self._grammars[segment_index]._next_token_mask_from_state(local_state)
+        start = segment.profile.spec.token_offset
+        output[start : start + len(mask)] = mask
+        return output
+
+    def is_complete(self, tokens: Sequence[int]) -> bool:
+        """Whether the prefix completes every segment exactly once."""
+        state = self._consume(tokens)
+        return state is not None and state[0] == len(self.segments)
+
+
+class ActionCodec2Router:
+    "Route heterogeneous dataset states into physical token namespaces."
+
+    model_type = ROUTER_MODEL_TYPE
+
+    def __init__(
+        self,
+        profiles: Sequence[tuple[ProfileSpec, ActionCodec2Processor]],
+        presets: Sequence[PresetConfig],
+    ) -> None:
+        runtimes: dict[str, _ProfileRuntime] = {}
+        expected_offset = 0
+        for spec, processor in profiles:
+            if spec.name in runtimes:
+                raise ConfigError(f"duplicate physical profile {spec.name!r}")
+            if spec.token_offset != expected_offset:
+                raise ConfigError(
+                    "profile token namespaces must be contiguous and ordered"
+                )
+            if processor.vocab_size > spec.token_budget:
+                raise ConfigError(
+                    f"profile {spec.name!r} uses {processor.vocab_size} tokens, "
+                    f"exceeding budget {spec.token_budget}"
+                )
+            if processor.artifact_fingerprint != spec.artifact_fingerprint:
+                raise ConfigError(
+                    f"profile {spec.name!r} artifact fingerprint does not match its processor"
+                )
+            if processor.config.set_bpe.allow_cross_component_merge:
+                raise ConfigError(
+                    "allow_cross_component_merge=true is not supported by the v1 router; "
+                    "a component-aware Set-BPE serializer and grammar are required"
+                )
+            runtimes[spec.name] = _ProfileRuntime(spec, processor)
+            expected_offset += spec.token_budget
+        if not runtimes or not set(runtimes) <= _PROFILES:
+            raise ConfigError(
+                "router requires joint and/or eef physical profiles"
+            )
+        for name, runtime in runtimes.items():
+            if runtime.processor.action_dim != _PROFILE_WIDTHS[name]:
+                raise ConfigError(
+                    f"profile {name!r} must have width {_PROFILE_WIDTHS[name]}, "
+                    f"got {runtime.processor.action_dim}"
+                )
+        self.profiles = MappingProxyType(runtimes)
+        self._source_directory = Path(__file__).resolve().parent.parent
+        self._grammar_cache = BoundedCache(8)
+        self._action_spaces: dict[str, PresetConfig] = {}
+        for preset in presets:
+            self.register_action_space(preset)
+        self.vocab_size = expected_offset
+
+    @property
+    def action_spaces(self) -> Mapping[str, PresetConfig]:
+        """Read-only registered built-in and user-created action spaces."""
+        return MappingProxyType(self._action_spaces)
+
+    def __str__(self) -> str:
+        return self.describe_action_spaces()
+
+    def describe_action_spaces(
+        self, *, selected: str | None = None, action_dim: int | None = None
+    ) -> str:
+        """Explain all layouts, or source-width candidates, using this artifact's state requirements."""
+        second_order_dims = {
+            name: tuple(
+                dimension
+                for component in runtime.processor.config.physical.components.values()
+                if component.primitive_order == 2
+                for dimension in component.dims
+            )
+            for name, runtime in self.profiles.items()
+        }
+        return format_action_spaces(
+            self.action_spaces,
+            selected=selected,
+            action_dim=action_dim,
+            second_order_dims=second_order_dims,
+        )
+
+    @classmethod
+    def from_processors(
+        cls,
+        processors: Mapping[str, ActionCodec2Processor],
+        *,
+        token_budgets: Mapping[str, int],
+        presets: Sequence[PresetConfig],
+    ) -> ActionCodec2Router:
+        """Assign stable contiguous namespaces in canonical joint/eef order."""
+        if set(processors) != set(token_budgets):
+            raise ConfigError("processors and token_budgets must share keys")
+        if set(processors) != _PROFILES:
+            raise ConfigError(
+                "processors must contain exactly the joint and eef profiles"
+            )
+        offset = 0
+        entries = []
+        for name in ("joint", "eef"):
+            processor = processors[name]
+            budget = _integer(
+                token_budgets[name], f"token_budgets.{name}", positive=True
+            )
+            spec = ProfileSpec(
+                name,
+                offset,
+                budget,
+                processor.artifact_fingerprint,
+            )
+            entries.append((spec, processor))
+            offset += budget
+        return cls(entries, presets)
+
+    def preset(self, name: str) -> PresetConfig:
+        """Resolve one preset or fail with the available names."""
+        try:
+            return self._action_spaces[name]
+        except KeyError as error:
+            raise KeyError(
+                f"unknown preset {name!r}; available: {sorted(self._action_spaces)}"
+            ) from error
+
+    def register_action_space(
+        self,
+        preset: PresetConfig | Mapping[str, object] | str | Path,
+    ) -> PresetConfig:
+        "Register a validated action-space config, mapping, or YAML file."
+        if isinstance(preset, Mapping):
+            preset = PresetConfig.from_dict(preset)
+        elif isinstance(preset, (str, Path)):
+            preset = PresetConfig.from_yaml(preset)
+        if not isinstance(preset, PresetConfig):
+            raise TypeError(
+                "register_action_space expects PresetConfig, a mapping, or a preset YAML path"
+            )
+        existing = self._action_spaces.get(preset.name)
+        if existing is not None and existing != preset:
+            raise ConfigError(
+                f"action-space name {preset.name!r} is already registered differently"
+            )
+        self._action_spaces[preset.name] = preset
+        return preset
+
+    def _segments(self, preset: PresetConfig) -> tuple[_Segment, ...]:
+        return tuple(
+            _Segment(component, self.profiles[component.space])
+            for component in preset.components
+        )
+
+    def encode_batch(
+        self,
+        inputs: np.ndarray,
+        *,
+        preset: str,
+        fps: float | None = None,
+        current_state: np.ndarray | None = None,
+        previous_first_order: Mapping[str, np.ndarray] | None = None,
+    ) -> list[list[int]]:
+        "Encode one regular-rate ``[B,T,D]`` tensor at ``fps``."
+        preset_config = self.preset(preset)
+        self._validate_boundary_keys(previous_first_order, preset_config)
+        canonical = preset_config.canonicalize(
+            inputs, source_hz=fps, current_state=current_state
+        )
+        batch = len(next(iter(canonical.values())))
+        rows: list[list[int]] = [[] for _ in range(batch)]
+        for segment in self._segments(preset_config):
+            values = canonical[segment.component.name]
+            streams = segment.profile.processor.encode_batch(
+                np.stack([trajectory.values for trajectory in values]),
+                active_dims=segment.component.active_dims,
+                previous_first_order=None
+                if previous_first_order is None
+                else previous_first_order.get(segment.component.name),
+            )
+            offset = segment.profile.spec.token_offset
+            for row, stream in zip(rows, streams, strict=True):
+                row.extend(offset + token for token in stream)
+        return rows
+
+    def route_trajectories(
+        self,
+        inputs: np.ndarray,
+        *,
+        preset: str,
+        current_state: np.ndarray | None = None,
+        fps: float | None = None,
+        previous_first_order: Mapping[str, np.ndarray] | None = None,
+    ) -> dict[str, list[ActiveTrajectory]]:
+        "Expose canonical complete trajectories grouped by physical profile."
+        preset_config = self.preset(preset)
+        self._validate_boundary_keys(previous_first_order, preset_config)
+        canonical = preset_config.canonicalize(
+            inputs, current_state=current_state, source_hz=fps
+        )
+        output: dict[str, list[ActiveTrajectory]] = {}
+        for component in preset_config.components:
+            trajectories = canonical[component.name]
+            processor = self.profiles[component.space].processor
+            previous = (
+                None
+                if previous_first_order is None
+                else previous_first_order.get(component.name)
+            )
+            dense = processor._dense_previous_first_order(
+                previous, component.active_dims, len(trajectories)
+            )
+            rows = (
+                [None] * len(trajectories)
+                if dense is None
+                else np.take(dense, component.active_dims, axis=1)
+            )
+            output.setdefault(component.space, []).extend(
+                ActiveTrajectory(t.values, t.active_dims, previous_first_order=p)
+                for t, p in zip(trajectories, rows, strict=True)
+            )
+        return output
+
+    def _validate_boundary_keys(
+        self,
+        previous_first_order: Mapping[str, np.ndarray] | None,
+        preset: PresetConfig,
+    ) -> None:
+        if previous_first_order is None:
+            previous_first_order = {}
+        if not isinstance(previous_first_order, Mapping):
+            raise ValueError(
+                "previous_first_order must map component names to canonical [B,D_active] boundaries"
+            )
+        unknown = set(previous_first_order) - {c.name for c in preset.components}
+        if unknown:
+            raise ValueError(
+                f"unknown previous_first_order component(s): {sorted(unknown)}"
+            )
+        required = {
+            c.name: f"(B, {len(c.active_dims)})"
+            for c in preset.components
+            if any(
+                p.primitive_order == 2 and set(c.active_dims).intersection(p.dims)
+                for p in self.profiles[
+                    c.space
+                ].processor.config.physical.components.values()
+            )
+        }
+        missing = set(required) - previous_first_order.keys()
+        if missing:
+            raise ValueError(
+                "second-order tokenization requires previous_first_order with arrays "
+                f"{required}; missing {sorted(missing)}. Use canonical {preset.target_hz:g} Hz "
+                "reconstructed increments. codec.first_order_template(batch_size) explicitly "
+                "creates zeros; use zeros only if the preceding increment is known to be zero."
+            )
+
+    def final_first_order(
+        self,
+        streams: Sequence[Sequence[int]],
+        *,
+        preset: str,
+        previous_first_order: Mapping[str, np.ndarray],
+        executed_steps: int | None = None,
+    ) -> dict[str, np.ndarray]:
+        "Return component ``[B,D_active]`` boundaries at the canonical clock."
+        preset_config = self.preset(preset)
+        if previous_first_order is None:
+            raise ValueError("final_first_order requires previous_first_order")
+        self._validate_boundary_keys(previous_first_order, preset_config)
+        segments = self._segments(preset_config)
+        steps = self._batch_steps(streams, segments)
+        split = [self._split_stream(stream, segments, steps) for stream in streams]
+        output = {}
+        for index, segment in enumerate(segments):
+            processor = segment.profile.processor
+            if not processor.requires_previous_first_order:
+                continue
+            output[segment.component.name] = processor.final_first_order(
+                [row[index] for row in split],
+                previous_first_order=previous_first_order.get(segment.component.name),
+                active_dims=segment.component.active_dims,
+                executed_steps=executed_steps,
+            )
+        return output
+
+    def _split_stream(
+        self, tokens: Sequence[int], segments: Sequence[_Segment], steps: int
+    ) -> list[list[int]]:
+        cursor = 0
+        output = []
+        for segment in segments:
+            grammar = segment.profile.processor.grammar(
+                steps, active_dims=segment.component.active_dims
+            )
+            state = grammar._initial_state()
+            local: list[int] = []
+            while cursor < len(tokens) and not grammar._state_is_complete(state):
+                raw_token = tokens[cursor]
+                if isinstance(raw_token, bool) or not isinstance(
+                    raw_token, (int, np.integer)
+                ):
+                    raise ValueError(f"tokens[{cursor}] must be an integer")
+                token = int(raw_token) - segment.profile.spec.token_offset
+                if not 0 <= token < segment.profile.processor.vocab_size:
+                    raise ValueError(
+                        "token belongs to the wrong routed profile namespace"
+                    )
+                next_state = grammar._advance(state, token)
+                if next_state is None:
+                    raise ValueError(
+                        f"Action token stream has invalid coverage for component {segment.component.name!r}. Constrain generation with codec.grammar(H, fps=...).next_token_mask(prefix)."
+                    )
+                state = next_state
+                local.append(token)
+                cursor += 1
+            if not grammar._state_is_complete(state):
+                raise ValueError(
+                    f"Incomplete action token stream for component {segment.component.name!r}. Check codec.grammar(H, fps=...).is_complete(tokens); discard or regenerate this row."
+                )
+            output.append(local)
+        if cursor != len(tokens):
+            raise ValueError(
+                "Action token stream has extra tokens after complete coverage; remove model prompt/EOS/padding before codec.decode()."
+            )
+        return output
+
+    def _token_cell_count(self, raw_token: object, *, index: int) -> int:
+        
+        if isinstance(raw_token, bool) or not isinstance(raw_token, (int, np.integer)):
+            raise ValueError(f"tokens[{index}] must be an integer")
+        token = int(raw_token)
+        for runtime in self.profiles.values():
+            local = token - runtime.spec.token_offset
+            if 0 <= local < runtime.processor.vocab_size:
+                return int(runtime.processor.serializer.token_cell_counts[local])
+        raise ValueError(f"tokens[{index}] is outside the routed profile vocabularies")
+
+    def _decoded_steps(
+        self, tokens: Sequence[int], segments: Sequence[_Segment]
+    ) -> int:
+        
+        if not tokens:
+            raise ValueError("token stream must not be empty")
+        cells_per_step = sum(len(segment.component.active_dims) for segment in segments)
+        represented_cells = sum(
+            self._token_cell_count(token, index=index)
+            for index, token in enumerate(tokens)
+        )
+        steps, remainder = divmod(represented_cells, cells_per_step)
+        if steps < 1 or remainder:
+            raise ValueError(
+                "Incomplete action token stream: "
+                f"{cells_per_step - remainder} more coordinate values are needed to finish a step. "
+                "Constrain generation with codec.grammar(H, fps=...).next_token_mask(prefix) "
+                "and check is_complete(tokens) for the intended H before decoding. "
+                "Use codec.batch_decode(..., errors='return') to isolate invalid rows; "
+                "do not pad truncated tokens with zeros."
+            )
+        return steps
+
+    def _batch_steps(
+        self,
+        streams: Sequence[Sequence[int]],
+        segments: Sequence[_Segment],
+    ) -> int:
+        
+        if not streams:
+            raise ValueError("streams must not be empty")
+        lengths = [self._decoded_steps(stream, segments) for stream in streams]
+        if len(set(lengths)) != 1:
+            raise ValueError(
+                f"all token streams must decode to the same length, got {lengths}; use codec.batch_decode(...) for independent variable-length outputs"
+            )
+        return lengths[0]
+
+    def decode_batch(
+        self,
+        streams: Sequence[Sequence[int]],
+        *,
+        preset: str,
+        fps: float | None = None,
+        current_state: np.ndarray | None = None,
+        previous_first_order: Mapping[str, np.ndarray] | None = None,
+    ) -> dict[str, np.ndarray]:
+        "Decode rows to deltas, or absolute components with ``current_state``."
+        preset_config = self.preset(preset)
+        self._validate_boundary_keys(previous_first_order, preset_config)
+        segments = self._segments(preset_config)
+        internal_steps = self._batch_steps(streams, segments)
+        states = _current_state_rows(
+            current_state, count=len(streams), input_dim=preset_config.input_dim
+        )
+        output_fps = preset_config.source_hz if fps is None else fps
+        output_steps = resampled_horizon(
+            internal_steps,
+            source_hz=preset_config.target_hz,
+            target_hz=output_fps,
+        )
+        output: dict[str, list[np.ndarray]] = {
+            component.name: [] for component in preset_config.components
+        }
+        split_streams = [
+            self._split_stream(stream, segments, internal_steps) for stream in streams
+        ]
+        for segment_index, segment in enumerate(segments):
+            decoded_batch = segment.profile.processor.decode_batch(
+                [split[segment_index] for split in split_streams],
+                active_dims=segment.component.active_dims,
+                previous_first_order=None
+                if previous_first_order is None
+                else previous_first_order.get(segment.component.name),
+            )
+            for decoded, state in zip(decoded_batch, states, strict=True):
+                restored = resample_canonical_trajectory(
+                    ActiveTrajectory(decoded, segment.component.active_dims),
+                    segment.component,
+                    source_hz=preset_config.target_hz,
+                    target_hz=output_fps,
+                    target_length=output_steps,
+                    method=preset_config.interpolation,
+                )
+                output[segment.component.name].append(
+                    externalize_canonical_trajectory(
+                        restored, segment.component, current_state=state
+                    )
+                )
+        return {name: np.stack(values) for name, values in output.items()}
+
+    def grammar(self, *, preset: str, horizon: int) -> RoutedActionCodec2Grammar:
+        """Build the global constrained grammar for one preset and target horizon."""
+        horizon = _integer(horizon, "horizon", positive=True)
+        self.preset(preset)
+        key = (preset, horizon)
+        grammar = self._grammar_cache.get(key)
+        if grammar is None:
+            grammar = RoutedActionCodec2Grammar(self, preset=preset, horizon=horizon)
+            self._grammar_cache[key] = grammar
+        return grammar
+
+    @property
+    def new_action_tokens(self) -> list[str]:
+        """Stable physical token names, including reserved profile budget slots."""
+        return [
+            f"<action_{name}_{index:04d}>"
+            for name, runtime in self.profiles.items()
+            for index in range(runtime.spec.token_budget)
+        ]
+
+    def save_pretrained(
+        self, directory: str | Path, *, include_code: bool = True
+    ) -> list[str]:
+        """Save one manifest plus isolated physical processor subdirectories."""
+        root = Path(directory)
+        files = []
+        for runtime in self.profiles.values():
+            files.extend(
+                runtime.processor.save_pretrained(root / "profiles" / runtime.spec.name)
+            )
+        manifest = {
+            "model_type": self.model_type,
+            "config_version": ROUTER_CONFIG_VERSION,
+            "profiles": [runtime.spec.to_dict() for runtime in self.profiles.values()],
+            "presets": [preset.to_dict() for preset in self.action_spaces.values()],
+        }
+        path = root / ROUTER_CONFIG_NAME
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(yaml.safe_dump(manifest, sort_keys=False), encoding="utf-8")
+        metadata = save_huggingface_metadata(
+            root,
+            model_type=self.model_type,
+            processor_class=type(self).__name__,
+            **(
+                {"auto_map": {"AutoProcessor": "processing_actioncodec2.ActionCodec2"}}
+                if include_code
+                else {}
+            ),
+        )
+        card = save_model_card(root, str(self))
+        if include_code:
+            from ..integration.exporting import ArtifactExporter
+
+            files.extend(
+                ArtifactExporter(root, source_directory=self._source_directory).export()
+            )
+        return [str(path), str(card), *map(str, metadata), *files]
+
+    @classmethod
+    def from_pretrained(
+        cls,
+        pretrained_model_name_or_path: str | Path,
+        **kwargs: object,
+    ) -> ActionCodec2Router | ActionCodec2:
+        "Load a router, or bind its public processor when given ``action_space``."
+        if "action_space" in kwargs:
+            from .processing_actioncodec2 import ActionCodec2
+
+            return ActionCodec2.from_pretrained(pretrained_model_name_or_path, **kwargs)
+        root = resolve_pretrained_directory(
+            pretrained_model_name_or_path,
+            allow_patterns=ROUTER_ALLOW_PATTERNS,
+            **kwargs,
+        )
+        path = root / ROUTER_CONFIG_NAME
+        payload = _mapping(
+            yaml.load(path.read_text(encoding="utf-8"), Loader=_UniqueKeyLoader),
+            "router",
+        )
+        _reject_unknown(
+            payload, {"model_type", "config_version", "profiles", "presets"}, "router"
+        )
+        if payload.get("model_type") != ROUTER_MODEL_TYPE:
+            raise ConfigError(f"router.model_type must be {ROUTER_MODEL_TYPE!r}")
+        if payload.get("config_version") != ROUTER_CONFIG_VERSION:
+            raise ConfigError(
+                f"unsupported router config_version {payload.get('config_version')!r}"
+            )
+        raw_profiles = payload.get("profiles")
+        raw_presets = payload.get("presets")
+        if not isinstance(raw_profiles, list) or not isinstance(raw_presets, list):
+            raise ConfigError("router.profiles and router.presets must be lists")
+        profiles = []
+        for index, raw in enumerate(raw_profiles):
+            spec = ProfileSpec.from_dict(raw, path=f"router.profiles[{index}]")
+            processor = ActionCodec2Processor.from_pretrained(
+                root / "profiles" / spec.name
+            )
+            profiles.append((spec, processor))
+        presets = [
+            PresetConfig.from_dict(raw, path=f"router.presets[{index}]")
+            for index, raw in enumerate(raw_presets)
+        ]
+        router = cls(profiles, presets)
+        router._source_directory = root
+        return router

runtime/tokenization/__init__.py

@@ -0,0 +1 @@
+"""Internal tokenization components for ActionCodec2."""

runtime/tokenization/bpe.py

@@ -0,0 +1,397 @@
+"Strict ``bpe.json`` I/O for both tokenization schemes."
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from numbers import Integral
+from pathlib import Path
+
+import numpy as np
+
+from ..common._validation import active_dimensions
+from .bpe_vocabulary import BPEVocabulary
+from ..physical.configuration import ActionCodec2Config, ConfigError
+from .setbpe_spatial import SpatialVocabulary
+from .setbpe_temporal import TemporalVocabulary
+
+BPE_NAME = "bpe.json"
+
+
+def _integer(value: object, path: str, *, positive: bool = False) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ConfigError(f"{path} must be an integer")
+    minimum = 1 if positive else 0
+    if value < minimum:
+        qualifier = "positive" if positive else "non-negative"
+        raise ConfigError(f"{path} must be {qualifier}")
+    return int(value)
+
+
+def _rules(payload: object, width: int, path: str) -> tuple[tuple[int, ...], ...]:
+    
+    if not isinstance(payload, Sequence) or isinstance(
+        payload, (str, bytes, bytearray)
+    ):
+        raise ConfigError(f"{path} must be a list")
+    output = []
+    for rank, raw_rule in enumerate(payload):
+        rule_path = f"{path}[{rank}]"
+        if not isinstance(raw_rule, Sequence) or isinstance(
+            raw_rule, (str, bytes, bytearray)
+        ):
+            raise ConfigError(f"{rule_path} must be a list of {width} integers")
+        if len(raw_rule) != width:
+            raise ConfigError(f"{rule_path} must contain exactly {width} integers")
+        output.append(
+            tuple(
+                _integer(value, f"{rule_path}[{index}]")
+                for index, value in enumerate(raw_rule)
+            )
+        )
+    return tuple(output)
+
+
+def _unique_json_object(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    output: dict[str, object] = {}
+    for key, value in pairs:
+        if key in output:
+            raise ConfigError(f"{BPE_NAME} contains duplicate field {key!r}")
+        output[key] = value
+    return output
+
+
+def _validate_rule_references(
+    *,
+    atom_count: int,
+    lookahead: int,
+    spatial_merges: tuple[tuple[int, int], ...],
+    temporal_merges: tuple[tuple[int, int, int], ...],
+) -> None:
+    
+    for rank, (left, right) in enumerate(spatial_merges):
+        child = atom_count + rank
+        if left >= child or right >= child:
+            raise ConfigError(
+                f"spatial_merges[{rank}] must reference already-created tokens"
+            )
+    spatial_size = atom_count + len(spatial_merges)
+    for rank, (left, right, offset) in enumerate(temporal_merges):
+        child = spatial_size + rank
+        if left >= child or right >= child:
+            raise ConfigError(
+                f"temporal_merges[{rank}] must reference already-created tokens"
+            )
+        if not 1 <= offset < lookahead:
+            raise ConfigError(
+                f"temporal_merges[{rank}] offset must be positive and smaller than lookahead"
+            )
+
+
+def _read_payload(directory: str | Path) -> dict[str, object]:
+    
+    path = Path(directory) / BPE_NAME
+    try:
+        return json.loads(
+            path.read_text(encoding="utf-8"), object_pairs_hook=_unique_json_object
+        )
+    except OSError:
+        raise
+    except json.JSONDecodeError as error:
+        raise ConfigError(f"cannot parse {path}: {error}") from error
+
+
+def _dense_cells(
+    cells: np.ndarray,
+    bins: Sequence[int],
+    active_dims: Sequence[int] | None,
+) -> tuple[np.ndarray, tuple[int, ...] | None]:
+    
+    raw = np.asarray(cells)
+    if raw.dtype.kind not in {"i", "u"}:
+        raise ValueError("cells must contain integer indices")
+    values = np.asarray(raw, dtype=np.int64)
+    if values.ndim != 2 or len(values) < 1 or values.shape[1] < 1:
+        raise ValueError("cells must have non-empty shape [T, D_active]")
+    if active_dims is None:
+        if values.shape[1] > len(bins):
+            raise ValueError(f"cells width exceeds codebook dimension {len(bins)}")
+        if values.shape[1] < len(bins):
+            dimensions = tuple(range(values.shape[1]))
+            dense = np.full((len(values), len(bins)), -1, dtype=np.int64)
+            dense[:, : values.shape[1]] = values
+            values = dense
+        else:
+            dimensions = None
+    else:
+        dimensions = active_dimensions(active_dims, len(bins))
+        if len(dimensions) != values.shape[1]:
+            raise ValueError(
+                "active_dims must have one entry per compact cell coordinate"
+            )
+        if np.any(values < 0):
+            raise ValueError("compact cells must not contain -1")
+        dense = np.full((len(values), len(bins)), -1, dtype=np.int64)
+        dense[:, dimensions] = values
+        values = dense
+    counts = np.asarray(tuple(int(value) for value in bins), dtype=np.int64)
+    if np.any(values < -1) or np.any(values >= counts[None, :]):
+        raise ValueError("cells contain an invalid active or absent index")
+    return values, dimensions
+
+
+class SetBPESerializer:
+    "Lossless mapping between ``[T,D]`` physical cells and token IDs."
+
+    scheme = "set_bpe"
+
+    def __init__(
+        self,
+        *,
+        bins: Sequence[int],
+        lookahead: int,
+        spatial_merges: Sequence[Sequence[int]],
+        temporal_merges: Sequence[Sequence[int]],
+    ) -> None:
+        self.lookahead = _integer(lookahead, "lookahead", positive=True)
+        self.bins = tuple(
+            _integer(value, f"bins[{index}]", positive=True)
+            for index, value in enumerate(bins)
+        )
+        if not self.bins:
+            raise ConfigError("bins must contain at least one cell slot")
+        self.spatial_merges = _rules(spatial_merges, 2, "spatial_merges")
+        self.temporal_merges = _rules(temporal_merges, 3, "temporal_merges")
+        _validate_rule_references(
+            atom_count=sum(self.bins),
+            lookahead=self.lookahead,
+            spatial_merges=self.spatial_merges,
+            temporal_merges=self.temporal_merges,
+        )
+        try:
+            self.spatial = SpatialVocabulary(self.bins, self.spatial_merges)
+            self.vocabulary = TemporalVocabulary(
+                self.spatial, self.lookahead, self.temporal_merges
+            )
+        except ValueError as error:
+            raise ConfigError(str(error)) from error
+        self.patterns = self.vocabulary.patterns
+        self.root = self.vocabulary.root
+        self.vocab_size = self.vocabulary.vocab_size
+        self.token_cell_counts = np.asarray(
+            [
+                sum(
+                    int(self.spatial.support[spatial_token]).bit_count()
+                    for _, spatial_token in self.patterns[token]
+                )
+                for token in range(self.vocab_size)
+            ],
+            dtype=np.int64,
+        )
+
+    def encode(
+        self,
+        cells: np.ndarray,
+        *,
+        active_dims: Sequence[int] | None = None,
+    ) -> list[int]:
+        "Serialize one non-empty trajectory without emitting absent slots."
+        values, _ = _dense_cells(cells, self.bins, active_dims)
+        return self.vocabulary.encode(values)
+
+    def decode(
+        self,
+        tokens: Sequence[int],
+        *,
+        active_dims: Sequence[int] | None = None,
+    ) -> np.ndarray:
+        """Recover dense cells, writing ``-1`` in semantically absent slots."""
+        if len(tokens) < 1:
+            raise ValueError("token stream must not be empty")
+        checked = []
+        for index, token in enumerate(tokens):
+            if isinstance(token, bool) or not isinstance(token, Integral):
+                raise ValueError(f"tokens[{index}] must be an integer")
+            value = int(token)
+            if not 0 <= value < self.vocab_size:
+                raise ValueError(f"tokens[{index}] is outside the vocabulary")
+            checked.append(value)
+        return self.vocabulary.decode(checked, active_dims=active_dims)
+
+    def to_dict(self) -> dict[str, object]:
+        """Return the intentionally minimal, path-independent BPE artifact."""
+        return {
+            "spatial_merges": [list(rule) for rule in self.spatial_merges],
+            "temporal_merges": [list(rule) for rule in self.temporal_merges],
+        }
+
+    @classmethod
+    def from_dict(
+        cls,
+        payload: object,
+        *,
+        bins: Sequence[int],
+        lookahead: int,
+    ) -> SetBPESerializer:
+        if not isinstance(payload, Mapping) or not all(
+            isinstance(key, str) for key in payload
+        ):
+            raise ConfigError(f"{BPE_NAME} must contain one JSON object")
+        allowed = {"spatial_merges", "temporal_merges"}
+        unknown = sorted(set(payload) - allowed)
+        if unknown:
+            raise ConfigError(
+                f"{BPE_NAME} contains unknown field(s): {', '.join(unknown)}"
+            )
+        missing = sorted(allowed - set(payload))
+        if missing:
+            raise ConfigError(f"{BPE_NAME} is missing field(s): {', '.join(missing)}")
+        return cls(
+            bins=bins,
+            lookahead=lookahead,
+            spatial_merges=payload["spatial_merges"],
+            temporal_merges=payload["temporal_merges"],
+        )
+
+    @classmethod
+    def from_pretrained(
+        cls,
+        directory: str | Path,
+        *,
+        bins: Sequence[int],
+        lookahead: int,
+    ) -> SetBPESerializer:
+        return cls.from_dict(_read_payload(directory), bins=bins, lookahead=lookahead)
+
+    def save_pretrained(self, directory: str | Path) -> Path:
+        """Write ``bpe.json`` and return its path."""
+        path = Path(directory) / BPE_NAME
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(self.to_dict(), indent=2) + "\n", encoding="utf-8")
+        return path
+
+
+class BPESerializer:
+    "Lossless mapping between ``[T,D]`` physical cells and plain-BPE ids."
+
+    scheme = "bpe"
+
+    def __init__(
+        self,
+        *,
+        bins: Sequence[int],
+        lookahead: int,
+        merges: Sequence[Sequence[int]],
+    ) -> None:
+        self.lookahead = _integer(lookahead, "lookahead", positive=True)
+        self.bins = tuple(
+            _integer(value, f"bins[{index}]", positive=True)
+            for index, value in enumerate(bins)
+        )
+        if not self.bins:
+            raise ConfigError("bins must contain at least one cell slot")
+        self.merges = _rules(merges, 2, "merges")
+        atom_count = sum(self.bins)
+        for rank, (left, right) in enumerate(self.merges):
+            child = atom_count + rank
+            if left >= child or right >= child:
+                raise ConfigError(
+                    f"merges[{rank}] must reference already-created tokens"
+                )
+        try:
+            self.vocabulary = BPEVocabulary(self.bins, self.merges)
+        except ValueError as error:
+            raise ConfigError(str(error)) from error
+        self.max_token_cells = self.lookahead * len(self.bins)
+        self.token_cell_counts = self.vocabulary.token_cells
+        oversized = int(np.count_nonzero(self.token_cell_counts > self.max_token_cells))
+        if oversized:
+            raise ConfigError(
+                f"{oversized} merge rule(s) cover more than the {self.max_token_cells} "
+                "primitive cells allowed by lookahead"
+            )
+        self.vocab_size = self.vocabulary.vocab_size
+
+    def encode(
+        self,
+        cells: np.ndarray,
+        *,
+        active_dims: Sequence[int] | None = None,
+    ) -> list[int]:
+        "Serialize one non-empty trajectory without emitting absent slots."
+        values, _ = _dense_cells(cells, self.bins, active_dims)
+        return self.vocabulary.encode(values)
+
+    def decode(
+        self,
+        tokens: Sequence[int],
+        *,
+        active_dims: Sequence[int] | None = None,
+    ) -> np.ndarray:
+        """Recover dense cells, writing ``-1`` in semantically absent slots."""
+        if len(tokens) < 1:
+            raise ValueError("token stream must not be empty")
+        checked = []
+        for index, token in enumerate(tokens):
+            if isinstance(token, bool) or not isinstance(token, Integral):
+                raise ValueError(f"tokens[{index}] must be an integer")
+            value = int(token)
+            if not 0 <= value < self.vocab_size:
+                raise ValueError(f"tokens[{index}] is outside the vocabulary")
+            checked.append(value)
+        return self.vocabulary.decode(checked, active_dims=active_dims)
+
+    def to_dict(self) -> dict[str, object]:
+        """Return the intentionally minimal, path-independent BPE artifact."""
+        return {"merges": [list(rule) for rule in self.merges]}
+
+    @classmethod
+    def from_dict(
+        cls,
+        payload: object,
+        *,
+        bins: Sequence[int],
+        lookahead: int,
+    ) -> BPESerializer:
+        if not isinstance(payload, Mapping) or not all(
+            isinstance(key, str) for key in payload
+        ):
+            raise ConfigError(f"{BPE_NAME} must contain one JSON object")
+        unknown = sorted(set(payload) - {"merges"})
+        if unknown:
+            raise ConfigError(
+                f"{BPE_NAME} contains unknown field(s): {', '.join(unknown)}"
+            )
+        if "merges" not in payload:
+            raise ConfigError(f"{BPE_NAME} is missing field(s): merges")
+        return cls(bins=bins, lookahead=lookahead, merges=payload["merges"])
+
+    @classmethod
+    def from_pretrained(
+        cls,
+        directory: str | Path,
+        *,
+        bins: Sequence[int],
+        lookahead: int,
+    ) -> BPESerializer:
+        return cls.from_dict(_read_payload(directory), bins=bins, lookahead=lookahead)
+
+    def save_pretrained(self, directory: str | Path) -> Path:
+        """Write ``bpe.json`` and return its path."""
+        path = Path(directory) / BPE_NAME
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(self.to_dict(), indent=2) + "\n", encoding="utf-8")
+        return path
+
+
+SERIALIZERS: dict[str, type[SetBPESerializer] | type[BPESerializer]] = {
+    SetBPESerializer.scheme: SetBPESerializer,
+    BPESerializer.scheme: BPESerializer,
+}
+
+
+def serializer_class(
+    config: ActionCodec2Config,
+) -> type[SetBPESerializer] | type[BPESerializer]:
+    """Return the serializer the configured tokenization scheme requires."""
+    return SERIALIZERS[config.set_bpe.scheme]

runtime/tokenization/bpe_training.py

@@ -0,0 +1,235 @@
+"Plain-BPE fitting implementations."
+
+from __future__ import annotations
+
+import heapq
+from collections import defaultdict
+from collections.abc import Iterable, Iterator, Sequence
+
+import numpy as np
+
+from .bpe_vocabulary import BPEVocabulary
+from ..backend.native_backend import require_native, resolve_backend
+
+__all__ = ["train_bpe", "cell_chunks"]
+
+
+def cell_chunks(
+    episodes: Iterable[np.ndarray],
+    *,
+    max_chunk_rows: int = 1_000_000,
+) -> Iterator[tuple[np.ndarray, np.ndarray]]:
+    "Yield ``(cells, episode_offsets)`` blocks for the native trainer."
+    chunks = getattr(episodes, "chunks", None)
+    offsets = getattr(episodes, "offsets", None)
+    if getattr(episodes, "_actioncodec2_validated", False) and chunks is not None:
+        for index, (codes, bounds) in enumerate(zip(chunks, offsets, strict=True)):
+            if codes is None:
+                raise RuntimeError("cell corpus chunk has already been consumed")
+            yield (
+                np.ascontiguousarray(codes),
+                np.ascontiguousarray(bounds, dtype=np.int64),
+            )
+            episodes.release_chunk(index)
+        return
+    pending: list[np.ndarray] = []
+    lengths: list[int] = []
+    rows = 0
+
+    def flush() -> tuple[np.ndarray, np.ndarray]:
+        block = np.concatenate(pending, axis=0)
+        bounds = np.concatenate(([0], np.cumsum(lengths, dtype=np.int64)))
+        pending.clear()
+        lengths.clear()
+        return np.ascontiguousarray(block), bounds
+
+    for episode in episodes:
+        values = np.asarray(episode)
+        if values.dtype.kind not in {"i", "u"}:
+            raise ValueError("episodes must contain integer cell indices")
+        if values.ndim != 2 or len(values) < 1:
+            raise ValueError("every episode must have non-empty shape [T, D]")
+        pending.append(values)
+        lengths.append(len(values))
+        rows += len(values)
+        if rows >= max_chunk_rows:
+            yield flush()
+            rows = 0
+    if pending:
+        yield flush()
+
+
+def _flatten(
+    chunks: Iterable[tuple[np.ndarray, np.ndarray]], bins: Sequence[int]
+) -> tuple[list[list[int]], int]:
+    
+    counts = np.asarray(tuple(int(value) for value in bins), dtype=np.int64)
+    offsets = np.concatenate(([0], np.cumsum(counts)))
+    streams: list[list[int]] = []
+    actions = 0
+    for codes, bounds in chunks:
+        values = np.asarray(codes, dtype=np.int64)
+        if values.ndim != 2 or values.shape[1] != len(counts):
+            raise ValueError("cells must have one column per bin count")
+        if np.any(values < -1) or np.any(values >= counts[None, :]):
+            raise ValueError("cells must contain -1 or an in-range cell index")
+        for start, stop in zip(bounds[:-1], bounds[1:], strict=True):
+            episode = values[int(start) : int(stop)]
+            if not len(episode):
+                raise ValueError("every episode must be non-empty")
+            support = episode >= 0
+            if np.any(support != support[:1]):
+                raise ValueError(
+                    "active dimensions must remain constant within an episode"
+                )
+            present = np.flatnonzero(support[0])
+            if not len(present):
+                raise ValueError(
+                    "every control step needs at least one active coordinate"
+                )
+            shifted = episode[:, present] + offsets[present][None, :]
+            streams.append(shifted.reshape(-1).tolist())
+            actions += len(episode)
+    if not streams:
+        raise ValueError("BPE training requires at least one complete trajectory")
+    return streams, actions
+
+
+def _train_bpe_python(
+    chunks: Iterable[tuple[np.ndarray, np.ndarray]],
+    bins: Sequence[int],
+    *,
+    vocab_size: int,
+    max_token_cells: int,
+    progress: bool = False,
+) -> tuple[BPEVocabulary, dict[str, object]]:
+    
+    atoms = int(sum(int(value) for value in bins))
+    if vocab_size < atoms:
+        raise ValueError(
+            f"vocab_size {vocab_size} is below the {atoms} primitive atoms"
+        )
+    if max_token_cells < 1:
+        raise ValueError("max_token_cells must be positive")
+    streams, actions = _flatten(chunks, bins)
+    initial_length = sum(len(stream) for stream in streams)
+    length = initial_length
+
+    counts: dict[tuple[int, int], int] = defaultdict(int)
+    carriers: dict[tuple[int, int], set[int]] = defaultdict(set)
+    for index, stream in enumerate(streams):
+        for pair in zip(stream[:-1], stream[1:], strict=True):
+            counts[pair] += 1
+            carriers[pair].add(index)
+    heap = [(-value, pair) for pair, value in counts.items()]
+    heapq.heapify(heap)
+
+    token_cells = [1] * atoms
+    merges: list[tuple[int, int]] = []
+    oversized: set[tuple[int, int]] = set()
+    observed_cells = 1
+    while len(merges) + atoms < vocab_size and heap:
+        negative, pair = heapq.heappop(heap)
+        frequency = counts.get(pair, 0)
+        if frequency <= 0 or frequency != -negative or pair in oversized:
+            continue
+        span = token_cells[pair[0]] + token_cells[pair[1]]
+        if span > max_token_cells:
+            oversized.add(pair)
+            continue
+        child = atoms + len(merges)
+        token_cells.append(span)
+        observed_cells = max(observed_cells, span)
+        touched: set[tuple[int, int]] = set()
+        for index in sorted(carriers.pop(pair, ())):
+            stream = streams[index]
+            output: list[int] = []
+            position = 0
+            while position < len(stream):
+                if (
+                    position + 1 < len(stream)
+                    and stream[position] == pair[0]
+                    and stream[position + 1] == pair[1]
+                ):
+                    if output:
+                        counts[(output[-1], pair[0])] -= 1
+                        touched.add((output[-1], pair[0]))
+                        counts[(output[-1], child)] += 1
+                        carriers[(output[-1], child)].add(index)
+                        touched.add((output[-1], child))
+                    if position + 2 < len(stream):
+                        follower = stream[position + 2]
+                        counts[(pair[1], follower)] -= 1
+                        touched.add((pair[1], follower))
+                        counts[(child, follower)] += 1
+                        carriers[(child, follower)].add(index)
+                        touched.add((child, follower))
+                    counts[pair] -= 1
+                    length -= 1
+                    output.append(child)
+                    position += 2
+                else:
+                    output.append(stream[position])
+                    position += 1
+            streams[index] = output
+        merges.append(pair)
+        for member in touched:
+            value = counts.get(member, 0)
+            if value > 0:
+                heapq.heappush(heap, (-value, member))
+        if progress and len(merges) % 256 == 0:
+            print(
+                f"  bpe merge {len(merges):>5}  tokens/action {length / actions:.4f}",
+                flush=True,
+            )
+
+    vocabulary = BPEVocabulary(tuple(int(value) for value in bins), tuple(merges))
+    report: dict[str, object] = {
+        "episodes": len(streams),
+        "actions": actions,
+        "atoms": atoms,
+        "merges": len(merges),
+        "vocab_size": vocabulary.vocab_size,
+        "cells": initial_length,
+        "tokens_per_action_initial": initial_length / actions,
+        "tokens_per_action": length / actions,
+        "compression": initial_length / length,
+        "max_token_cells": int(max_token_cells),
+        "max_token_cells_observed": observed_cells,
+        "oversized_pairs_skipped": len(oversized),
+        "trainer": "python_sparse_exact",
+    }
+    return vocabulary, report
+
+
+def train_bpe(
+    episodes: Iterable[np.ndarray],
+    bins: Sequence[int],
+    *,
+    vocab_size: int,
+    max_token_cells: int,
+    backend: str = "auto",
+    progress: bool = False,
+    threads: int = 0,
+) -> tuple[BPEVocabulary, dict[str, object]]:
+    "Fit plain BPE on the row-major flattened primitive-cell stream."
+    if resolve_backend(backend) == "python":
+        return _train_bpe_python(
+            cell_chunks(episodes),
+            bins,
+            vocab_size=vocab_size,
+            max_token_cells=max_token_cells,
+            progress=progress,
+        )
+    merges, report = require_native().train_bpe(
+        cell_chunks(episodes),
+        [int(count) for count in bins],
+        int(vocab_size),
+        int(max_token_cells),
+        int(threads),
+    )
+    vocabulary = BPEVocabulary(
+        tuple(int(count) for count in bins),
+        tuple((int(left), int(right)) for left, right in merges),
+    )
+    return vocabulary, dict(report)

runtime/tokenization/bpe_vocabulary.py

@@ -0,0 +1,159 @@
+"Runtime plain-BPE vocabulary over the row-major flattened cell stream."
+
+from __future__ import annotations
+
+import heapq
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+import numpy as np
+
+from ..common._validation import active_dimensions
+
+__all__ = ["BPEVocabulary"]
+
+
+@dataclass
+class BPEVocabulary:
+    """Primitive atoms plus ordered, adjacency-based merge rules."""
+
+    bins: tuple[int, ...]
+    merges: tuple[tuple[int, int], ...]
+
+    def __post_init__(self) -> None:
+        if not self.bins or any(count < 1 for count in self.bins):
+            raise ValueError("every dimension needs at least one bin")
+        self.offsets = np.concatenate(
+            ([0], np.cumsum(np.asarray(self.bins, dtype=np.int64)))
+        )
+        self.atom_count = int(self.offsets[-1])
+        self.vocab_size = self.atom_count + len(self.merges)
+        atom_dims = np.repeat(
+            np.arange(len(self.bins), dtype=np.int64),
+            np.asarray(self.bins, dtype=np.int64),
+        )
+
+
+        expansions: list[tuple[int, ...]] = [
+            (token,) for token in range(self.atom_count)
+        ]
+        for rank, (left, right) in enumerate(self.merges):
+            token = self.atom_count + rank
+            if not 0 <= left < token or not 0 <= right < token:
+                raise ValueError("a merge rule must reference already-created tokens")
+            expansions.append(expansions[left] + expansions[right])
+        self.expansions = tuple(expansions)
+        self.token_dims = tuple(
+            tuple(int(atom_dims[atom]) for atom in expansion)
+            for expansion in expansions
+        )
+        self.token_cells = np.asarray(
+            [len(expansion) for expansion in expansions], dtype=np.int64
+        )
+        self._rules = {
+            (int(left), int(right)): (self.atom_count + rank, rank)
+            for rank, (left, right) in enumerate(self.merges)
+        }
+
+    @property
+    def dimension(self) -> int:
+        return len(self.bins)
+
+    def atom(self, dimension: int, value: int) -> int:
+        return int(self.offsets[dimension]) + int(value)
+
+    def _flatten(self, values: np.ndarray, dimensions: tuple[int, ...]) -> list[int]:
+        
+        counts = np.asarray(self.bins, dtype=np.int64)
+        if np.any(values < -1) or np.any(values >= counts[None, :]):
+            raise ValueError("cells contain an invalid active or absent index")
+        support = values >= 0
+        if np.any(support != support[:1]):
+            raise ValueError(
+                "active dimensions must remain constant within a trajectory"
+            )
+        present = tuple(int(dim) for dim in np.flatnonzero(support[0]))
+        if present != dimensions:
+            raise ValueError("cells do not activate exactly the requested dimensions")
+        if not present:
+            raise ValueError("every control step needs at least one active coordinate")
+        active = values[:, list(present)]
+        base = np.asarray([int(self.offsets[dim]) for dim in present], dtype=np.int64)
+        return (active + base[None, :]).reshape(-1).tolist()
+
+    def encode(self, cells: np.ndarray) -> list[int]:
+        "Apply the merges greedily in creation-rank order to one trajectory."
+        values = np.asarray(cells, dtype=np.int64)
+        if values.ndim != 2 or len(values) < 1 or values.shape[1] < 1:
+            raise ValueError("cells must have non-empty shape [T, D]")
+        dimensions = tuple(int(dim) for dim in np.flatnonzero(values[0] >= 0))
+        stream = self._flatten(values, dimensions)
+        count = len(stream)
+        previous = list(range(-1, count - 1))
+        following = list(range(1, count + 1))
+        following[-1] = -1
+        alive = [True] * count
+        rules = self._rules
+        heap: list[tuple[int, int]] = []
+        for index in range(count - 1):
+            rule = rules.get((stream[index], stream[index + 1]))
+            if rule is not None:
+                heap.append((rule[1], index))
+        heapq.heapify(heap)
+        while heap:
+            rank, index = heapq.heappop(heap)
+            if not alive[index]:
+                continue
+            follower = following[index]
+            if follower < 0 or not alive[follower]:
+                continue
+            rule = rules.get((stream[index], stream[follower]))
+            if rule is None or rule[1] != rank:
+                continue
+            stream[index] = rule[0]
+            alive[follower] = False
+            after = following[follower]
+            following[index] = after
+            if after >= 0:
+                previous[after] = index
+                successor = rules.get((stream[index], stream[after]))
+                if successor is not None:
+                    heapq.heappush(heap, (successor[1], index))
+            before = previous[index]
+            if before >= 0:
+                predecessor = rules.get((stream[before], stream[index]))
+                if predecessor is not None:
+                    heapq.heappush(heap, (predecessor[1], before))
+        return [stream[index] for index in range(count) if alive[index]]
+
+    def decode(
+        self,
+        tokens: Sequence[int],
+        *,
+        active_dims: Sequence[int] | None = None,
+    ) -> np.ndarray:
+        """Expand tokens to dense cells, writing ``-1`` in absent coordinates."""
+        dimensions = active_dimensions(active_dims, self.dimension)
+        atoms: list[int] = []
+        for index, raw_token in enumerate(tokens):
+            token = int(raw_token)
+            if not 0 <= token < self.vocab_size:
+                raise ValueError(f"tokens[{index}] is outside the vocabulary")
+            atoms.extend(self.expansions[token])
+        width = len(dimensions)
+        if not atoms or len(atoms) % width:
+            raise ValueError(
+                "token stream does not cover a whole number of routed control steps"
+            )
+        values = np.asarray(atoms, dtype=np.int64).reshape(-1, width)
+        starts = np.asarray(
+            [int(self.offsets[dim]) for dim in dimensions], dtype=np.int64
+        )
+        stops = np.asarray(
+            [int(self.offsets[dim + 1]) for dim in dimensions], dtype=np.int64
+        )
+        if np.any(values < starts[None, :]) or np.any(values >= stops[None, :]):
+            raise ValueError("token stream does not follow the routed dimension order")
+        cells = np.full((len(values), self.dimension), -1, dtype=np.int64)
+        cells[:, list(dimensions)] = values - starts[None, :]
+        return cells

runtime/tokenization/generation.py

@@ -0,0 +1,122 @@
+"""Explicit action-token constraints for Hugging Face generate()."""
+
+from __future__ import annotations
+
+import torch
+from transformers import LogitsProcessor
+
+from ..routing.cache import BoundedCache
+
+
+class ActionCodec2LogitsProcessor(LogitsProcessor):
+    "Constrain generated action IDs, then allow EOS only at complete coverage."
+
+    def __init__(
+        self,
+        codec,
+        horizon,
+        *,
+        fps,
+        prompt_length,
+        eos_token_id,
+        token_offset=0,
+        pad_token_id=None,
+    ):
+        for name, value in {
+            "prompt_length": prompt_length,
+            "eos_token_id": eos_token_id,
+            "token_offset": token_offset,
+        }.items():
+            if type(value) is not int or value < 0:
+                raise ValueError(f"{name} must be a nonnegative integer")
+        if pad_token_id is not None and (
+            type(pad_token_id) is not int or pad_token_id < 0
+        ):
+            raise ValueError("pad_token_id must be a nonnegative integer")
+        self.grammar = codec.grammar(horizon, fps=fps)
+        self.prompt_length = prompt_length
+        self.eos_token_id = eos_token_id
+        self.pad_token_id = pad_token_id
+        self.token_offset = token_offset
+        stop = token_offset + self.grammar.vocab_size
+        if token_offset <= eos_token_id < stop:
+            raise ValueError("eos_token_id must be outside the action token interval")
+        if pad_token_id is not None and token_offset <= pad_token_id < stop:
+            raise ValueError("pad_token_id must be outside the action token interval")
+        self._mask_cache = BoundedCache(64)
+
+    def _state(self, row):
+        if self.eos_token_id in row:
+            end = row.index(self.eos_token_id)
+            if any(t not in (self.eos_token_id, self.pad_token_id) for t in row[end:]):
+                raise ValueError(
+                    "only EOS/padding may follow completed action generation"
+                )
+            tokens = [t - self.token_offset for t in row[:end]]
+            if not self.grammar.is_complete(tokens):
+                raise ValueError("EOS occurred before action coverage was complete")
+        else:
+            tokens = [t - self.token_offset for t in row]
+        state = self.grammar._consume(tokens)
+        if state is None:
+            raise ValueError(
+                "generated prefix violates the action grammar; check prompt_length and token_offset"
+            )
+        return state
+
+    def _mask(self, state, scores):
+        key = (state, str(scores.device), scores.shape[-1])
+        mask = self._mask_cache.get(key)
+        if mask is None:
+            mask = torch.zeros(scores.shape[-1], device=scores.device, dtype=torch.bool)
+            index, local = state
+            if index == len(self.grammar.segments):
+                mask[self.eos_token_id] = True
+            else:
+                segment = self.grammar.segments[index]
+                allowed = self.grammar._grammars[index]._next_token_mask_from_state(
+                    local
+                )
+                start = self.token_offset + segment.profile.spec.token_offset
+                mask[start : start + len(allowed)] = torch.as_tensor(
+                    allowed, device=scores.device
+                )
+            self._mask_cache[key] = mask
+        return mask
+
+    def __call__(
+        self, input_ids: torch.LongTensor, scores: torch.FloatTensor
+    ) -> torch.FloatTensor:
+        if (
+            input_ids.ndim != 2
+            or scores.ndim != 2
+            or input_ids.shape[0] != scores.shape[0]
+        ):
+            raise ValueError(
+                "expected input_ids(B,L) and scores(B,V) with the same batch size"
+            )
+        if input_ids.shape[1] < self.prompt_length:
+            raise ValueError("prompt_length exceeds the supplied input length")
+        required = max(
+            self.token_offset + self.grammar.vocab_size,
+            self.eos_token_id + 1,
+            0 if self.pad_token_id is None else self.pad_token_id + 1,
+        )
+        if scores.shape[1] < required:
+            raise ValueError(
+                "model vocabulary does not cover configured action/EOS/padding IDs"
+            )
+        rows = input_ids[:, self.prompt_length :].detach().cpu().tolist()
+        output = scores.clone()
+        groups = {}
+        for index, row in enumerate(rows):
+            groups.setdefault(self._state(row), []).append(index)
+        for state, indices in groups.items():
+            output[indices] = scores[indices].masked_fill(
+                ~self._mask(state, scores), -torch.inf
+            )
+        if not torch.isfinite(output).any(dim=1).all():
+            raise ValueError(
+                "all legal action logits were suppressed; check other generation processors"
+            )
+        return output

runtime/tokenization/grammar.py

@@ -0,0 +1,209 @@
+"""Constrained-generation grammars for the two ActionCodec2 BPE schemes."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from numbers import Integral
+
+import numpy as np
+
+from ..common._validation import active_dimensions
+from .bpe import BPESerializer, SetBPESerializer
+from ..routing.cache import BoundedCache
+
+
+class _PrefixGrammar:
+    
+
+    def next_token_mask(self, tokens: Sequence[int]) -> np.ndarray:
+        """Return a boolean vocabulary mask for the next generated token."""
+        state = self._state(tokens)
+        if state is None:
+            raise ValueError("token prefix is not a legal ActionCodec2 stream")
+        return self._next_token_mask_from_state(state)
+
+    def is_complete(self, tokens: Sequence[int]) -> bool:
+        """Whether ``tokens`` is exactly one complete trajectory of this horizon."""
+        state = self._state(tokens)
+        return state is not None and self._state_is_complete(state)
+
+
+class ActionCodec2Grammar(_PrefixGrammar):
+    "Prefix grammar for one exact, fixed-horizon rooted token stream."
+
+    def __init__(
+        self,
+        serializer: SetBPESerializer,
+        *,
+        horizon: int,
+        active_dims: Sequence[int] | None = None,
+    ) -> None:
+        if isinstance(horizon, bool) or not isinstance(horizon, int) or horizon < 1:
+            raise ValueError("horizon must be a positive integer")
+        self.horizon = horizon
+        self.vocab_size = serializer.vocab_size
+        dims = active_dimensions(active_dims, serializer.spatial.dimension)
+        self._full = sum(1 << dimension for dimension in dims)
+        self._root_anchor = np.asarray(
+            [
+                serializer.spatial.anchor[serializer.root[token]]
+                for token in range(self.vocab_size)
+            ],
+            dtype=np.int64,
+        )
+        self._patterns = tuple(
+            tuple(
+                (offset, int(serializer.spatial.support[spatial_token]))
+                for offset, spatial_token in serializer.patterns[token]
+            )
+            for token in range(self.vocab_size)
+        )
+        self._mask_cache = BoundedCache(64)
+        self._state_cache = BoundedCache(256)
+        self._state_cache[()] = self._initial_state()
+
+    def _advance(self, state: tuple[int, ...], token: int) -> tuple[int, ...] | None:
+        if not 0 <= token < self.vocab_size:
+            return None
+        coverage = list(state)
+        front = next(
+            (index for index, mask in enumerate(coverage) if mask != self._full),
+            self.horizon,
+        )
+        if front == self.horizon:
+            return None
+        uncovered = self._full & ~coverage[front]
+        expected_anchor = int(uncovered & -uncovered).bit_length() - 1
+        if int(self._root_anchor[token]) != expected_anchor:
+            return None
+        for offset, support in self._patterns[token]:
+            step = front + offset
+            if step >= self.horizon or coverage[step] & support:
+                return None
+            coverage[step] |= support
+        return tuple(coverage)
+
+    def _initial_state(self) -> tuple[int, ...]:
+        
+        return (0,) * self.horizon
+
+    def _state_is_complete(self, state: tuple[int, ...]) -> bool:
+        
+        return all(mask == self._full for mask in state)
+
+    def _state(self, tokens: Sequence[int]) -> tuple[int, ...] | None:
+        checked: list[int] = []
+        for raw_token in tokens:
+            if isinstance(raw_token, bool) or not isinstance(raw_token, Integral):
+                return None
+            checked.append(int(raw_token))
+        key = tuple(checked)
+        if not key:
+            return self._initial_state()
+        missing = object()
+        cached = self._state_cache.get(key, missing)
+        if cached is not missing:
+            return cached
+        parent = key[:-1]
+        state = self._state_cache.get(parent, missing)
+        if state is missing:
+            state = self._initial_state()
+            for token in parent:
+                state = self._advance(state, token)
+                if state is None:
+                    break
+            self._state_cache[parent] = state
+        if state is not None:
+            state = self._advance(state, key[-1])
+        self._state_cache[key] = state
+        return state
+
+    def _next_token_mask_from_state(self, state: tuple[int, ...]) -> np.ndarray:
+        
+        if self._state_is_complete(state):
+            return np.zeros(self.vocab_size, dtype=bool)
+        cached = self._mask_cache.get(state)
+        if cached is not None:
+            return cached.copy()
+        front = next(index for index, mask in enumerate(state) if mask != self._full)
+        uncovered = self._full & ~state[front]
+        expected_anchor = int(uncovered & -uncovered).bit_length() - 1
+        mask = self._root_anchor == expected_anchor
+        for token in np.flatnonzero(mask):
+            for offset, support in self._patterns[int(token)]:
+                step = front + offset
+                if step >= self.horizon or state[step] & support:
+                    mask[token] = False
+                    break
+        self._mask_cache[state] = mask
+        return mask.copy()
+
+
+class ActionCodec2BPEGrammar(_PrefixGrammar):
+    "Prefix grammar for one exact, fixed-horizon plain-BPE token stream."
+
+    def __init__(
+        self,
+        serializer: BPESerializer,
+        *,
+        horizon: int,
+        active_dims: Sequence[int] | None = None,
+    ) -> None:
+        if isinstance(horizon, bool) or not isinstance(horizon, int) or horizon < 1:
+            raise ValueError("horizon must be a positive integer")
+        self.horizon = horizon
+        self.vocab_size = serializer.vocab_size
+        dims = active_dimensions(active_dims, serializer.vocabulary.dimension)
+        self._width = len(dims)
+        self._cells = horizon * self._width
+        self._token_cells = np.asarray(serializer.token_cell_counts, dtype=np.int64)
+        token_dims = serializer.vocabulary.token_dims
+        self._phase = np.zeros((self._width, self.vocab_size), dtype=bool)
+        for phase in range(self._width):
+            for token in range(self.vocab_size):
+                expansion = token_dims[token]
+                self._phase[phase, token] = all(
+                    dimension == dims[(phase + offset) % self._width]
+                    for offset, dimension in enumerate(expansion)
+                )
+        self._mask_cache = BoundedCache(64)
+
+    def _initial_state(self) -> tuple[int, ...]:
+        return (0,)
+
+    def _state_is_complete(self, state: tuple[int, ...]) -> bool:
+        return state[0] == self._cells
+
+    def _advance(self, state: tuple[int, ...], token: int) -> tuple[int, ...] | None:
+        if not 0 <= token < self.vocab_size:
+            return None
+        covered = state[0]
+        length = int(self._token_cells[token])
+        if covered + length > self._cells:
+            return None
+        if not self._phase[covered % self._width, token]:
+            return None
+        return (covered + length,)
+
+    def _state(self, tokens: Sequence[int]) -> tuple[int, ...] | None:
+        state: tuple[int, ...] | None = self._initial_state()
+        for raw_token in tokens:
+            if isinstance(raw_token, bool) or not isinstance(raw_token, Integral):
+                return None
+            assert state is not None
+            state = self._advance(state, int(raw_token))
+            if state is None:
+                return None
+        return state
+
+    def _next_token_mask_from_state(self, state: tuple[int, ...]) -> np.ndarray:
+        covered = state[0]
+        if covered == self._cells:
+            return np.zeros(self.vocab_size, dtype=bool)
+        cached = self._mask_cache.get(covered)
+        if cached is None:
+            cached = self._phase[covered % self._width] & (
+                self._token_cells <= self._cells - covered
+            )
+            self._mask_cache[covered] = cached
+        return cached.copy()

runtime/tokenization/setbpe_spatial.py

@@ -0,0 +1,177 @@
+"""Runtime spatial Set-BPE vocabulary and lossless row serialization."""
+
+from __future__ import annotations
+
+import heapq
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+
+import numpy as np
+
+from ..common._validation import active_dimensions
+
+__all__ = ["SpatialVocabulary", "aggregate_records"]
+
+
+def aggregate_records(
+    codes: np.ndarray, bins: Sequence[int] | None = None
+) -> tuple[np.ndarray, np.ndarray]:
+    "Lossless micro-aggregation of identical quantized actions."
+    values = np.asarray(codes, dtype=np.int64)
+    if values.ndim != 2:
+        raise ValueError("codes must have shape [U, D]")
+    if bins is not None:
+        dimensions = tuple(int(count) for count in bins)
+        if len(dimensions) != values.shape[1]:
+            raise ValueError("bins must have one entry per code coordinate")
+        counts = np.asarray(dimensions, dtype=np.int64)
+        valid = values >= 0
+        if np.any(values < -1) or np.any(values >= counts[None, :]):
+            raise ValueError("codes must contain -1 or an in-range cell index")
+        cardinality = int(np.prod(np.asarray(dimensions, dtype=object)))
+        if np.all(valid) and cardinality <= np.iinfo(np.int64).max:
+            keys = np.ravel_multi_index(values.T, dimensions)
+            unique_keys, counts = np.unique(keys, return_counts=True)
+            unique = np.stack(np.unravel_index(unique_keys, dimensions), axis=1)
+            return unique.astype(np.int64, copy=False), counts.astype(np.int64)
+    unique, counts = np.unique(values, axis=0, return_counts=True)
+    return unique, counts.astype(np.int64)
+
+
+@dataclass
+class SpatialVocabulary:
+    """Atoms, merge rules and the decoder metadata they induce."""
+
+    bins: tuple[int, ...]
+    merges: tuple[tuple[int, int], ...]
+
+    def __post_init__(self) -> None:
+        if not self.bins or any(count < 1 for count in self.bins):
+            raise ValueError("every dimension needs at least one bin")
+        self.offsets = np.concatenate(
+            ([0], np.cumsum(np.asarray(self.bins, dtype=np.int64)))
+        )
+        self.atom_count = int(self.offsets[-1])
+        self.vocab_size = self.atom_count + len(self.merges)
+        dimension = len(self.bins)
+        support = np.zeros(self.vocab_size, dtype=np.int64)
+        expansion = np.full((self.vocab_size, dimension), -1, dtype=np.int64)
+        for index, count in enumerate(self.bins):
+            for value in range(count):
+                token = int(self.offsets[index]) + value
+                support[token] = 1 << index
+                expansion[token, index] = value
+        for rank, (left, right) in enumerate(self.merges):
+            token = self.atom_count + rank
+            if left >= token or right >= token:
+                raise ValueError("a merge rule must reference already-created tokens")
+            if support[left] & support[right]:
+                raise ValueError("a merge rule joins two overlapping supports")
+            support[token] = support[left] | support[right]
+            merged = np.maximum(expansion[left], expansion[right])
+            expansion[token] = merged
+        self.support = support
+        self.expansion = expansion
+        self.anchor = np.asarray(
+            [int(mask & -mask).bit_length() - 1 for mask in support], dtype=np.int64
+        )
+        self.full_support = (1 << dimension) - 1
+        self._rules: dict[tuple[int, int], tuple[int, int]] = {}
+        for rank, (left, right) in enumerate(self.merges):
+            key = (min(left, right), max(left, right))
+            self._rules[key] = (self.atom_count + rank, rank)
+
+    @property
+    def dimension(self) -> int:
+        return len(self.bins)
+
+    def atom(self, dimension: int, value: int) -> int:
+        return int(self.offsets[dimension]) + int(value)
+
+    def encode(
+        self,
+        code: Sequence[int],
+        *,
+        active_dims: Sequence[int] | None = None,
+    ) -> list[int]:
+        "Deterministic online Set-BPE encoding (Algorithm 8)."
+        compact = [int(value) for value in code]
+        if active_dims is None:
+            if len(compact) != self.dimension:
+                raise ValueError(
+                    f"a dense quantized action must have {self.dimension} slots"
+                )
+            pairs = enumerate(compact)
+        else:
+            dimensions = active_dimensions(active_dims, self.dimension)
+            if len(dimensions) != len(compact):
+                raise ValueError(
+                    "active_dims must have one entry per compact coordinate"
+                )
+            pairs = zip(dimensions, compact, strict=True)
+        tokens = set()
+        for index, value in pairs:
+            if value == -1:
+                if active_dims is not None:
+                    raise ValueError("compact coordinates must not contain -1")
+                continue
+            if not 0 <= value < self.bins[index]:
+                raise ValueError(f"bin {value} is out of range for dimension {index}")
+            tokens.add(self.atom(index, value))
+        if not tokens:
+            raise ValueError(
+                "a quantized action must contain at least one active coordinate"
+            )
+        heap: list[tuple[int, int, int, int]] = []
+        ordered = sorted(tokens)
+        for position, left in enumerate(ordered):
+            for right in ordered[position + 1 :]:
+                rule = self._rules.get((left, right))
+                if rule is not None:
+                    heapq.heappush(heap, (rule[1], rule[0], left, right))
+        while heap:
+            _, child, left, right = heapq.heappop(heap)
+            if left not in tokens or right not in tokens:
+                continue
+            tokens.discard(left)
+            tokens.discard(right)
+            for other in tokens:
+                key = (min(child, other), max(child, other))
+                rule = self._rules.get(key)
+                if rule is not None:
+                    heapq.heappush(heap, (rule[1], rule[0], key[0], key[1]))
+            tokens.add(child)
+        return self.serialize(tokens)
+
+    def serialize(self, tokens: Iterable[int]) -> list[int]:
+        "Canonical order for autoregressive supervision."
+        return sorted(tokens, key=lambda token: (int(self.anchor[token]), int(token)))
+
+    def decode(
+        self,
+        tokens: Sequence[int],
+        *,
+        active_dims: Sequence[int] | None = None,
+    ) -> np.ndarray:
+        """Expand tokens to a dense row, using ``-1`` for absent coordinates."""
+        code = np.full(self.dimension, -1, dtype=np.int64)
+        covered = 0
+        for token in tokens:
+            value = int(token)
+            if not 0 <= value < self.vocab_size:
+                raise ValueError(f"token {value} is outside the vocabulary")
+            if covered & int(self.support[value]):
+                raise ValueError("token supports overlap; this is not a valid action")
+            covered |= int(self.support[value])
+            local = self.expansion[value]
+            code = np.where(local >= 0, local, code)
+        if active_dims is None:
+            expected = self.full_support
+        else:
+            dimensions = active_dimensions(active_dims, self.dimension)
+            expected = sum(1 << dimension for dimension in dimensions)
+        if covered != expected:
+            raise ValueError(
+                "token set does not exactly cover the requested active dimensions"
+            )
+        return code

runtime/tokenization/setbpe_spatial_training.py

@@ -0,0 +1,311 @@
+"Spatial Set-BPE fitting implementations."
+
+from __future__ import annotations
+
+import heapq
+from collections.abc import Sequence
+
+import numpy as np
+
+from ..backend.native_backend import require_native, resolve_backend
+from .setbpe_spatial import SpatialVocabulary
+
+__all__ = ["train_spatial"]
+
+
+class _SparseSpatialTrainer:
+    
+
+    def __init__(
+        self,
+        codes: np.ndarray,
+        weights: np.ndarray,
+        bins: Sequence[int],
+    ) -> None:
+        self.bins = tuple(int(value) for value in bins)
+        self.dimension = len(self.bins)
+        self.records = np.asarray(codes, dtype=np.int64)
+        self.weights = np.asarray(weights, dtype=np.int64)
+        if self.records.ndim != 2 or self.records.shape[1] != self.dimension:
+            raise ValueError("codes must have shape [U, D] matching the bin counts")
+        if self.weights.shape != (self.records.shape[0],):
+            raise ValueError("weights must have one entry per record")
+        counts = np.asarray(self.bins, dtype=np.int64)
+        if np.any(self.records < -1) or np.any(self.records >= counts[None, :]):
+            raise ValueError("codes must contain -1 or an in-range cell index")
+        if np.any(np.all(self.records < 0, axis=1)):
+            raise ValueError("every record must contain at least one active coordinate")
+        self.count = int(self.records.shape[0])
+        self.offsets = np.concatenate(
+            ([0], np.cumsum(np.asarray(self.bins, dtype=np.int64)))
+        )
+        self.atom_count = int(self.offsets[-1])
+
+        self.occurrence: list[np.ndarray] = []
+        self.support: list[int] = []
+        self.anchor: list[int] = []
+        self.frequency: list[int] = []
+        for index in range(self.dimension):
+            column = self.records[:, index]
+            for value in range(self.bins[index]):
+                members = np.flatnonzero(column == value).astype(np.int64)
+                self._append_token(members, 1 << index, index)
+        self._scratch = np.zeros(self.count, dtype=bool)
+        self.merges: list[tuple[int, int]] = []
+        self.statistics = {
+            "sparse_updates": 0,
+            "sparse_heap_rebuilds": 0,
+            "sparse_pair_types_peak": 0,
+        }
+
+        self.member = np.where(
+            self.records >= 0,
+            self.offsets[:-1][None, :] + self.records,
+            -1,
+        )
+        self._slot_pairs = tuple(
+            (first, second)
+            for first in range(self.dimension)
+            for second in range(first + 1, self.dimension)
+        )
+
+
+        self._sparse_counts: dict[int, int] | None = None
+        self._sparse_heap: list[tuple[int, int, int]] = []
+
+    def _append_token(self, members: np.ndarray, support: int, anchor: int) -> int:
+        token = len(self.occurrence)
+        self.occurrence.append(members)
+        self.support.append(support)
+        self.anchor.append(anchor)
+        self.frequency.append(int(self.weights[members].sum()) if members.size else 0)
+        return token
+
+    def _intersect(self, left: np.ndarray, right: np.ndarray) -> np.ndarray:
+        if left.size > right.size:
+            left, right = right, left
+        if left.size == 0:
+            return left
+        self._scratch[left] = True
+        result = right[self._scratch[right]]
+        self._scratch[left] = False
+        return result
+
+    @staticmethod
+    def _sparse_key(left: int, right: int) -> int:
+        low, high = (left, right) if left < right else (right, left)
+        return (int(low) << 32) | int(high)
+
+    @staticmethod
+    def _sparse_pair(key: int) -> tuple[int, int]:
+        return key >> 32, key & 0xFFFFFFFF
+
+    def build_sparse_index(self) -> None:
+        """Materialize exact counters only for currently observed pairs once."""
+        if self._sparse_counts is not None:
+            return
+        width = len(self.occurrence)
+        counts = np.zeros(width * width, dtype=np.int64)
+        for first, second in self._slot_pairs:
+            left = self.member[:, first]
+            right = self.member[:, second]
+            valid = (left >= 0) & (right >= 0)
+            if not valid.any():
+                continue
+            low = np.minimum(left[valid], right[valid])
+            high = np.maximum(left[valid], right[valid])
+            np.add.at(counts, low * width + high, self.weights[valid])
+        observed = np.flatnonzero(counts)
+        sparse: dict[int, int] = {}
+        heap: list[tuple[int, int, int]] = []
+        for packed in observed:
+            left, right = divmod(int(packed), width)
+            key = self._sparse_key(left, right)
+            value = int(counts[packed])
+            sparse[key] = value
+            heap.append((-value, left, right))
+        heapq.heapify(heap)
+        self._sparse_counts = sparse
+        self._sparse_heap = heap
+        self.statistics["sparse_pair_types_peak"] = len(sparse)
+
+    def sparse_best_pair(self) -> tuple[int, int, int] | None:
+        """Return the exact winner from the observed-pair max heap."""
+        if self._sparse_counts is None:
+            self.build_sparse_index()
+        assert self._sparse_counts is not None
+        while self._sparse_heap:
+            negative, left, right = heapq.heappop(self._sparse_heap)
+            value = self._sparse_counts.get(self._sparse_key(left, right), 0)
+            if value == -negative:
+                return left, right, value
+        return None
+
+    def _update_sparse_index(
+        self,
+        left: int,
+        right: int,
+        child: int,
+        rows: np.ndarray,
+        members: np.ndarray,
+        mass: int,
+    ) -> None:
+        if self._sparse_counts is None:
+            return
+        counts = self._sparse_counts
+        heap = self._sparse_heap
+        updates = 0
+
+        def change(key: int, delta: int) -> None:
+            nonlocal updates
+            new = counts.get(key, 0) + delta
+            if new < 0:
+                pair = self._sparse_pair(key)
+                raise RuntimeError(
+                    f"sparse spatial pair counter became negative for {pair}"
+                )
+            if new:
+                counts[key] = new
+                pair = self._sparse_pair(key)
+                heapq.heappush(heap, (-new, pair[0], pair[1]))
+            else:
+                counts.pop(key, None)
+            updates += 1
+
+        change(self._sparse_key(left, right), -mass)
+        other_mass = np.zeros(len(self.occurrence), dtype=np.int64)
+        weights = self.weights[members]
+        for slot in range(rows.shape[1]):
+            values = rows[:, slot]
+            valid = (values >= 0) & (values != left) & (values != right)
+            if valid.any():
+                np.add.at(other_mass, values[valid], weights[valid])
+        for raw_other in np.flatnonzero(other_mass):
+            other = int(raw_other)
+            value = int(other_mass[other])
+            change(self._sparse_key(left, other), -value)
+            change(self._sparse_key(right, other), -value)
+            change(self._sparse_key(child, other), value)
+
+        self.statistics["sparse_updates"] += updates
+        self.statistics["sparse_pair_types_peak"] = max(
+            self.statistics["sparse_pair_types_peak"], len(counts)
+        )
+        if len(heap) > 2 * len(counts) + 65_536:
+            self._sparse_heap = [
+                (-value, *self._sparse_pair(key)) for key, value in counts.items()
+            ]
+            heapq.heapify(self._sparse_heap)
+            self.statistics["sparse_heap_rebuilds"] += 1
+
+    def merge(self, left: int, right: int) -> int:
+        """Apply one exact incremental merge update."""
+        members = self._intersect(self.occurrence[left], self.occurrence[right])
+        mass = int(self.weights[members].sum()) if members.size else 0
+        rows = self.member[members] if members.size else self.member[:0].copy()
+        self.occurrence[left] = np.setdiff1d(
+            self.occurrence[left], members, assume_unique=True
+        )
+        self.occurrence[right] = np.setdiff1d(
+            self.occurrence[right], members, assume_unique=True
+        )
+        self.frequency[left] -= mass
+        self.frequency[right] -= mass
+        token = self._append_token(
+            members,
+            self.support[left] | self.support[right],
+            min(self.anchor[left], self.anchor[right]),
+        )
+        self._update_sparse_index(left, right, token, rows, members, mass)
+
+
+        if members.size:
+            rows[rows == right] = -1
+            rows[rows == left] = token
+            self.member[members] = rows
+        self.merges.append((left, right))
+        return token
+
+
+def _train_spatial_python(
+    codes: np.ndarray,
+    weights: np.ndarray,
+    bins: Sequence[int],
+    *,
+    vocab_size: int,
+    progress: bool = False,
+) -> tuple[SpatialVocabulary, dict[str, object]]:
+    
+    trainer = _SparseSpatialTrainer(codes, weights, bins)
+    if vocab_size < trainer.atom_count:
+        raise ValueError(
+            f"vocab_size {vocab_size} is below the {trainer.atom_count} primitive atoms"
+        )
+    total_weight = int(trainer.weights.sum())
+    active_width = np.sum(trainer.records >= 0, axis=1, dtype=np.int64)
+    initial = int(np.dot(trainer.weights, active_width))
+    length = initial
+    trainer.build_sparse_index()
+    for step in range(vocab_size - trainer.atom_count):
+        winner = trainer.sparse_best_pair()
+        if winner is None:
+            break
+        left, right, frequency = winner
+        trainer.merge(left, right)
+        length -= frequency
+        if progress and step % 256 == 0:
+            print(
+                f"  merge {step:>5}  tokens/action {length / total_weight:.4f}",
+                flush=True,
+            )
+    vocabulary = SpatialVocabulary(
+        tuple(int(value) for value in bins), tuple(trainer.merges)
+    )
+    report = {
+        "records": int(trainer.count),
+        "weight": total_weight,
+        "atoms": trainer.atom_count,
+        "merges": len(trainer.merges),
+        "vocab_size": vocabulary.vocab_size,
+        "tokens_per_action_initial": initial / total_weight,
+        "tokens_per_action": length / total_weight,
+        "compression": initial / length,
+        "sparse_updates": trainer.statistics["sparse_updates"],
+        "sparse_heap_rebuilds": trainer.statistics["sparse_heap_rebuilds"],
+        "sparse_pair_types_peak": trainer.statistics["sparse_pair_types_peak"],
+    }
+    return vocabulary, report
+
+
+def train_spatial(
+    codes: np.ndarray,
+    weights: np.ndarray,
+    bins: Sequence[int],
+    *,
+    vocab_size: int,
+    backend: str = "auto",
+    progress: bool = False,
+    **kwargs: object,
+) -> tuple[SpatialVocabulary, dict[str, object]]:
+    "Fit spatial Set-BPE, preferring the native kernel when it is built."
+    if resolve_backend(backend) == "python":
+
+
+        kwargs.pop("threads", None)
+        return _train_spatial_python(
+            codes, weights, bins, vocab_size=vocab_size, progress=progress, **kwargs
+        )
+    values = np.ascontiguousarray(codes, dtype=np.int32)
+    masses = np.ascontiguousarray(weights, dtype=np.int64)
+    merges, report = require_native().train_spatial(
+        values,
+        masses,
+        [int(count) for count in bins],
+        int(vocab_size),
+        int(kwargs.get("threads", 0)),
+    )
+    vocabulary = SpatialVocabulary(
+        tuple(int(count) for count in bins),
+        tuple((int(left), int(right)) for left, right in merges),
+    )
+    return vocabulary, dict(report)

runtime/tokenization/setbpe_temporal.py

@@ -0,0 +1,258 @@
+"""Runtime rooted-temporal Set-BPE vocabulary and lossless serialization."""
+
+from __future__ import annotations
+
+import heapq
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+import numpy as np
+
+from ..common._validation import active_dimensions
+from .setbpe_spatial import SpatialVocabulary
+
+__all__ = ["TemporalVocabulary"]
+
+Rule = tuple[int, int, int]
+Pattern = tuple[tuple[int, int], ...]
+
+
+def _active_support(active_dims: Sequence[int] | None, dimension: int) -> int:
+    dims = active_dimensions(active_dims, dimension)
+    return sum(1 << value for value in dims)
+
+
+def _validate_episode(values: np.ndarray, spatial: SpatialVocabulary) -> int:
+    if values.ndim != 2 or values.shape[1] != spatial.dimension or len(values) < 1:
+        raise ValueError(
+            f"every episode must have non-empty shape [T, {spatial.dimension}], got {values.shape}"
+        )
+    counts = np.asarray(spatial.bins, dtype=np.int64)
+    if np.any(values < -1) or np.any(values >= counts[None, :]):
+        raise ValueError("episodes must contain -1 or an in-range cell index")
+    support = values >= 0
+    if np.any(np.sum(support, axis=1) == 0):
+        raise ValueError("every timestep needs at least one active coordinate")
+    if np.any(support != support[:1]):
+        raise ValueError("active dimensions must remain constant within an episode")
+    return sum(1 << int(value) for value in np.flatnonzero(support[0]))
+
+
+@dataclass
+class TemporalVocabulary:
+    """A spatial vocabulary plus rooted, forward-only temporal merge rules."""
+
+    spatial: SpatialVocabulary
+    lookahead: int
+    merges: tuple[Rule, ...]
+
+    def __post_init__(self) -> None:
+        if self.lookahead < 1:
+            raise ValueError("lookahead must be positive")
+        self.patterns: list[Pattern] = [
+            ((0, token),) for token in range(self.spatial.vocab_size)
+        ]
+        self.spans: list[int] = [1] * self.spatial.vocab_size
+        self.root: list[int] = list(range(self.spatial.vocab_size))
+        self.support_masks: list[tuple[int, ...]] = [
+            (int(self.spatial.support[token]),)
+            for token in range(self.spatial.vocab_size)
+        ]
+        self._rules: dict[Rule, tuple[int, int]] = {}
+        for rank, rule in enumerate(self.merges):
+            left, right, offset = (int(value) for value in rule)
+            child = self.spatial.vocab_size + rank
+            if left >= child or right >= child or left < 0 or right < 0:
+                raise ValueError(
+                    "a temporal merge must reference already-created tokens"
+                )
+            pattern, masks = _merge_pattern(
+                self.patterns[left],
+                self.patterns[right],
+                offset,
+                self.lookahead,
+                self.spatial,
+            )
+            self.patterns.append(pattern)
+            self.spans.append(len(masks))
+            self.root.append(self.root[left])
+            self.support_masks.append(masks)
+            key = (left, right, offset)
+            if key in self._rules:
+                raise ValueError("duplicate temporal merge rule")
+            self._rules[key] = (child, rank)
+
+    @property
+    def vocab_size(self) -> int:
+        return self.spatial.vocab_size + len(self.merges)
+
+    def encode(self, codes: np.ndarray) -> list[int]:
+        """Encode a dense episode; ``-1`` slots are semantically absent."""
+        values = np.asarray(codes, dtype=np.int64)
+        _validate_episode(values, self.spatial)
+
+        at: list[dict[int, int]] = [dict() for _ in range(values.shape[0])]
+        tokens: list[int] = []
+        anchors: list[int] = []
+        active: list[bool] = []
+        for anchor, row in enumerate(values):
+            for token in self.spatial.encode(row):
+                instance = len(tokens)
+                tokens.append(token)
+                anchors.append(anchor)
+                active.append(True)
+                at[anchor][token] = instance
+
+        frontier: list[tuple[int, int, int, int, int, int]] = []
+
+        def offer(left_instance: int, right_instance: int) -> None:
+            left = tokens[left_instance]
+            right = tokens[right_instance]
+            offset = anchors[right_instance] - anchors[left_instance]
+            rule = self._rules.get((left, right, offset))
+            if rule is not None:
+                child, rank = rule
+                heapq.heappush(
+                    frontier,
+                    (
+                        rank,
+                        anchors[left_instance],
+                        int(self.spatial.anchor[self.root[child]]),
+                        left_instance,
+                        right_instance,
+                        child,
+                    ),
+                )
+
+        for anchor, left_items in enumerate(at):
+            for offset in range(1, min(self.lookahead, len(at) - anchor)):
+                for left_instance in left_items.values():
+                    for right_instance in at[anchor + offset].values():
+                        offer(left_instance, right_instance)
+
+        while frontier:
+            _, anchor, _, left_instance, right_instance, child = heapq.heappop(frontier)
+            if not active[left_instance] or not active[right_instance]:
+                continue
+            if anchors[left_instance] != anchor:
+                continue
+            rule = (
+                tokens[left_instance],
+                tokens[right_instance],
+                anchors[right_instance] - anchor,
+            )
+            resolved = self._rules.get(rule)
+            if resolved is None or resolved[0] != child:
+                continue
+
+            active[left_instance] = False
+            active[right_instance] = False
+            del at[anchor][tokens[left_instance]]
+            del at[anchors[right_instance]][tokens[right_instance]]
+            new_instance = len(tokens)
+            tokens.append(child)
+            anchors.append(anchor)
+            active.append(True)
+            at[anchor][child] = new_instance
+
+            for offset in range(1, self.lookahead):
+                future = anchor + offset
+                if future < len(at):
+                    for other in at[future].values():
+                        offer(new_instance, other)
+                past = anchor - offset
+                if past >= 0:
+                    for other in at[past].values():
+                        offer(other, new_instance)
+
+        ordered: list[tuple[int, int, int]] = []
+        for anchor, instances in enumerate(at):
+            for token, instance in instances.items():
+                if active[instance]:
+                    ordered.append(
+                        (anchor, int(self.spatial.anchor[self.root[token]]), token)
+                    )
+        ordered.sort()
+        return [token for _, _, token in ordered]
+
+    def decode(
+        self,
+        stream: Sequence[int],
+        *,
+        active_dims: Sequence[int] | None = None,
+    ) -> np.ndarray:
+        """Decode ids using the route's requested active-dimension support."""
+        if not stream:
+            return np.empty((0, self.spatial.dimension), dtype=np.int64)
+        full = _active_support(active_dims, self.spatial.dimension)
+        coverage: list[int] = [0]
+        spatial_tokens: list[list[int]] = [[]]
+        front = 0
+        for raw_token in stream:
+            token = int(raw_token)
+            if not 0 <= token < self.vocab_size:
+                raise ValueError(f"temporal token {token} is outside the vocabulary")
+            while front < len(coverage) and coverage[front] == full:
+                front += 1
+            if front == len(coverage):
+                coverage.append(0)
+                spatial_tokens.append([])
+
+            uncovered = full & ~coverage[front]
+            expected_anchor = int(uncovered & -uncovered).bit_length() - 1
+            actual_anchor = int(self.spatial.anchor[self.root[token]])
+            if actual_anchor != expected_anchor:
+                raise ValueError(
+                    "temporal stream violates root order at the earliest incomplete step"
+                )
+
+            for offset, spatial_token in self.patterns[token]:
+                step = front + offset
+                while step >= len(coverage):
+                    coverage.append(0)
+                    spatial_tokens.append([])
+                support = int(self.spatial.support[spatial_token])
+                if coverage[step] & support:
+                    raise ValueError(
+                        "temporal stream contains overlapping spatial support"
+                    )
+                coverage[step] |= support
+                spatial_tokens[step].append(spatial_token)
+
+        if any(mask != full for mask in coverage):
+            raise ValueError("temporal stream ended with an incomplete control step")
+        return np.stack(
+            [
+                self.spatial.decode(tokens, active_dims=active_dims)
+                for tokens in spatial_tokens
+            ]
+        )
+
+
+def _merge_pattern(
+    left: Pattern,
+    right: Pattern,
+    offset: int,
+    lookahead: int,
+    spatial: SpatialVocabulary,
+) -> tuple[Pattern, tuple[int, ...]]:
+    if not 1 <= offset < lookahead:
+        raise ValueError("a temporal merge offset must be in [1, lookahead)")
+    shifted = tuple((time + offset, token) for time, token in right)
+    pattern = tuple(sorted((*left, *shifted)))
+    span = 1 + max(time for time, _ in pattern)
+    if span > lookahead:
+        raise ValueError("temporal merge exceeds the lookahead horizon")
+    masks = [0] * span
+    roots = 0
+    for time, token in pattern:
+        support = int(spatial.support[token])
+        if masks[time] & support:
+            raise ValueError("temporal merge joins overlapping spatial supports")
+        masks[time] |= support
+        roots += int(time == 0)
+    if roots != 1:
+        raise ValueError(
+            "a rooted temporal token must have exactly one time-zero spatial token"
+        )
+    return pattern, tuple(masks)

runtime/tokenization/setbpe_temporal_training.py

@@ -0,0 +1,649 @@
+"Temporal Set-BPE fitting implementations."
+
+from __future__ import annotations
+
+import heapq
+from array import array
+from collections import Counter
+from collections.abc import Iterable, Iterator, Sequence
+
+import numpy as np
+
+from ..backend.native_backend import require_native, resolve_backend
+from .setbpe_spatial import SpatialVocabulary
+from .setbpe_temporal import (
+    Pattern,
+    Rule,
+    TemporalVocabulary,
+    _merge_pattern,
+    _validate_episode,
+)
+
+__all__ = ["train_temporal"]
+
+
+class _SparseTemporalTrainer:
+    
+
+    def __init__(
+        self,
+        episodes: Sequence[np.ndarray],
+        spatial: SpatialVocabulary,
+        lookahead: int,
+        max_vocab_size: int,
+    ) -> None:
+        if lookahead < 1:
+            raise ValueError("lookahead must be positive")
+        self.spatial = spatial
+        self.lookahead = lookahead
+        self.max_vocab_size = max_vocab_size
+        self.patterns: list[Pattern] = [
+            ((0, token),) for token in range(spatial.vocab_size)
+        ]
+        self.spans: list[int] = [1] * spatial.vocab_size
+        self.masks: list[tuple[int, ...]] = [
+            (int(spatial.support[token]),) for token in range(spatial.vocab_size)
+        ]
+        self._mask_table = np.zeros((max_vocab_size, lookahead), dtype=np.uint64)
+        self._mask_table[: spatial.vocab_size, 0] = spatial.support.astype(
+            np.uint64, copy=False
+        )
+        self.merges: list[Rule] = []
+        self.tokens = array("I")
+        self.anchors = array("I")
+        self.slots = array("I")
+        total_anchors = sum(len(episode) + lookahead for episode in episodes)
+        self.member = np.full((total_anchors, spatial.dimension), -1, dtype=np.int32)
+        self.occupied = np.zeros(total_anchors, dtype=np.uint64)
+        self._slot_mask = (1 << spatial.dimension) - 1
+        self.occurrences: list[dict[int, int]] = [
+            dict() for _ in range(spatial.vocab_size)
+        ]
+        self.episode_count = len(episodes)
+        self.action_count = sum(len(episode) for episode in episodes)
+        self.initial_count = 0
+        self.counts: dict[int, int] = {}
+        self.self_versions: dict[int, int] = {}
+        self.heap: list[tuple[int, int, int, int, int, bool]] = []
+        self.self_cache: dict[int, tuple[int, list[tuple[int, int]]]] = {}
+        self._legal_table = np.zeros(
+            (lookahead, max_vocab_size, max_vocab_size), dtype=np.uint8
+        )
+        for offset in range(1, lookahead):
+            self._legal_table[offset, : spatial.vocab_size, : spatial.vocab_size] = 2
+        self.statistics = Counter()
+        self._active_count = 0
+
+        self._load_episodes(episodes)
+        self.counts = self._initial_pair_counts()
+        self.heap = self._initial_heap()
+        self.statistics["initial_edge_types"] = len(self.counts)
+        self.statistics["initial_edges"] = sum(self.counts.values())
+
+    def _load_episodes(self, episodes: Sequence[np.ndarray]) -> None:
+        
+
+        base = 0
+        encoding_cache: dict[bytes, tuple[int, ...]] = {}
+        for episode in episodes:
+            values = np.asarray(episode, dtype=np.int64)
+            _validate_episode(values, self.spatial)
+            needed = base + len(values) + self.lookahead
+            for time, row in enumerate(values):
+                cache_key = row.tobytes()
+                encoded = encoding_cache.get(cache_key)
+                if encoded is None:
+                    encoded = tuple(self.spatial.encode(row))
+                    encoding_cache[cache_key] = encoded
+                anchor = base + time
+                for token in encoded:
+                    self._new_instance(token, anchor)
+                    self.initial_count += 1
+            base = needed
+
+    def _initial_pair_counts(self) -> dict[int, int]:
+        
+        base_vocab = self.spatial.vocab_size
+        dense_size = base_vocab * base_vocab * self.lookahead
+        if dense_size <= 1 << 25:
+            dense_counts = np.zeros(dense_size, dtype=np.int64)
+            for offset in range(1, self.lookahead):
+                left_rows = self.member[:-offset]
+                right_rows = self.member[offset:]
+                for left_slot in range(self.spatial.dimension):
+                    left = left_rows[:, left_slot]
+                    for right_slot in range(self.spatial.dimension):
+                        right = right_rows[:, right_slot]
+                        valid = (left >= 0) & (right >= 0)
+                        if not valid.any():
+                            continue
+                        packed = (
+                            left[valid].astype(np.int64) * base_vocab + right[valid]
+                        ) * self.lookahead + offset
+                        np.add.at(dense_counts, packed, 1)
+            initial_counts: dict[int, int] = {}
+            for raw_key in np.flatnonzero(dense_counts):
+                pair, offset = divmod(int(raw_key), self.lookahead)
+                left, right = divmod(pair, base_vocab)
+                packed_key = (
+                    left * self.max_vocab_size + right
+                ) * self.lookahead + offset
+                initial_counts[packed_key] = int(dense_counts[raw_key])
+            return initial_counts
+        return self._initial_pair_counts_sparse()
+
+    def _initial_pair_counts_sparse(self) -> dict[int, int]:
+        
+        fallback: Counter[int] = Counter()
+        for anchor, left_row in enumerate(self.member):
+            left_tokens = left_row[left_row >= 0]
+            for offset in range(1, self.lookahead):
+                target = anchor + offset
+                if target >= len(self.member):
+                    break
+                right_tokens = self.member[target]
+                right_tokens = right_tokens[right_tokens >= 0]
+                for raw_left in left_tokens:
+                    for raw_right in right_tokens:
+                        packed_key = (
+                            int(raw_left) * self.max_vocab_size + int(raw_right)
+                        ) * self.lookahead + offset
+                        fallback[packed_key] += 1
+        return dict(fallback)
+
+    def _initial_heap(self) -> list[tuple[int, int, int, int, int, bool]]:
+        heap: list[tuple[int, int, int, int, int, bool]] = []
+        for packed_key, count in self.counts.items():
+            pair, offset = divmod(packed_key, self.lookahead)
+            left, right = divmod(pair, self.max_vocab_size)
+            heap.append((-count, left, right, offset, 0, False))
+        heapq.heapify(heap)
+        return heap
+
+    def _new_instance(self, token: int, anchor: int) -> int:
+        while token >= len(self.occurrences):
+            self.occurrences.append({})
+        if anchor in self.occurrences[token]:
+            raise RuntimeError("a temporal type cannot occur twice at one anchor")
+        occupied = int(self.occupied[anchor])
+        available = self._slot_mask ^ occupied
+        if available == 0:
+            raise RuntimeError("temporal anchor exceeded the spatial token-width bound")
+        lowest = available & -available
+        slot = lowest.bit_length() - 1
+        self.occupied[anchor] = occupied | lowest
+        instance = len(self.tokens)
+        self.tokens.append(token)
+        self.anchors.append(anchor)
+        self.slots.append(slot)
+        self.member[anchor, slot] = token
+        self._active_count += 1
+        self.occurrences[token][anchor] = instance
+        return instance
+
+    def _initialize_legality(self, child: int) -> None:
+        
+        count = child + 1
+        spans = np.asarray(self.spans[:count], dtype=np.int64)
+        masks = self._mask_table[:count]
+        child_masks = self._mask_table[child]
+        child_span = self.spans[child]
+        for offset in range(1, self.lookahead):
+            overlap = np.zeros(count, dtype=bool)
+            for relative in range(self.lookahead - offset):
+                overlap |= (child_masks[offset + relative] & masks[:, relative]) != 0
+            legal = (offset + spans <= self.lookahead) & ~overlap
+            self._legal_table[offset, child, :count] = np.where(legal, 2, 1)
+
+            overlap.fill(False)
+            for relative in range(min(child_span, self.lookahead - offset)):
+                overlap |= (masks[:, offset + relative] & child_masks[relative]) != 0
+            legal = (offset + child_span <= self.lookahead) & ~overlap
+            self._legal_table[offset, :count, child] = np.where(legal, 2, 1)
+
+    def _entry(
+        self, packed_key: int, priority: int, certified: bool
+    ) -> tuple[int, int, int, int, int, bool]:
+        pair, offset = divmod(packed_key, self.lookahead)
+        left, right = divmod(pair, self.max_vocab_size)
+        return (
+            -priority,
+            left,
+            right,
+            offset,
+            self.self_versions.get(packed_key, 0) if left == right else 0,
+            certified,
+        )
+
+    def _select(self, key: Rule) -> list[tuple[int, int]]:
+        left, right, offset = key
+        left_occurrences = self.occurrences[left]
+        right_occurrences = self.occurrences[right]
+        if left != right:
+            return [
+                (left_instance, right_occurrences[anchor + offset])
+                for anchor, left_instance in left_occurrences.items()
+                if anchor + offset in right_occurrences
+            ]
+        selected: list[tuple[int, int]] = []
+        consumed: set[int] = set()
+        for anchor in sorted(left_occurrences):
+            target = anchor + offset
+            if (
+                anchor in consumed
+                or target in consumed
+                or target not in right_occurrences
+            ):
+                continue
+            selected.append((left_occurrences[anchor], right_occurrences[target]))
+            consumed.add(anchor)
+            consumed.add(target)
+        return selected
+
+    def best(self) -> tuple[Rule, list[tuple[int, int]]] | None:
+        while self.heap:
+            negative, left, right, offset, version, certified = heapq.heappop(self.heap)
+            self.statistics["heap_pops"] += 1
+            key = (left, right, offset)
+            packed_key = (left * self.max_vocab_size + right) * self.lookahead + offset
+            current_count = self.counts.get(packed_key, 0)
+            if current_count <= 0:
+                continue
+            if left == right:
+                current_version = self.self_versions.get(packed_key, 0)
+                stale = current_version != version
+            else:
+                stale = current_count != -negative
+            if stale:
+                heapq.heappush(self.heap, self._entry(packed_key, current_count, False))
+                continue
+            if left == right and not certified:
+                matches = self._select(key)
+                self.self_cache[packed_key] = (version, matches)
+                heapq.heappush(self.heap, self._entry(packed_key, len(matches), True))
+                self.statistics["self_certifications"] += 1
+                continue
+            if certified:
+                cached = self.self_cache.get(packed_key)
+                if cached is None or cached[0] != version:
+                    continue
+                matches = cached[1]
+            else:
+                matches = self._select(key)
+            gain = -negative
+            if len(matches) != gain:
+                raise RuntimeError(
+                    "sparse temporal counter disagrees with exact matching"
+                )
+            return key, matches
+        return None
+
+    def _accumulate_incident(
+        self,
+        instances: Sequence[int] | set[int],
+        multiplier: int,
+        deltas: Counter[int],
+    ) -> None:
+        
+        grouped: dict[int, list[int]] = {}
+        for instance in instances:
+            grouped.setdefault(self.tokens[instance], []).append(self.anchors[instance])
+        width = len(self.patterns)
+        total_anchors = self.member.shape[0]
+        vocab_width = self.max_vocab_size
+        lookahead = self.lookahead
+        for token, raw_anchors in grouped.items():
+            anchors = np.asarray(raw_anchors, dtype=np.int64)
+            for offset in range(1, self.lookahead):
+                future_anchors = anchors[anchors + offset < total_anchors] + offset
+                if future_anchors.size:
+                    values = self.member[future_anchors].reshape(-1)
+                    values = values[values >= 0]
+                    if values.size:
+                        counts = np.bincount(values, minlength=width)
+                        neighbors = np.flatnonzero(counts)
+                        neighbors = neighbors[
+                            self._legal_table[offset, token, neighbors] == 2
+                        ]
+                        for raw_neighbor in neighbors:
+                            neighbor = int(raw_neighbor)
+                            packed_key = (
+                                token * vocab_width + neighbor
+                            ) * lookahead + offset
+                            deltas[packed_key] += multiplier * int(counts[neighbor])
+                past_anchors = anchors[anchors >= offset] - offset
+                if past_anchors.size:
+                    values = self.member[past_anchors].reshape(-1)
+                    values = values[values >= 0]
+                    if values.size:
+                        counts = np.bincount(values, minlength=width)
+                        neighbors = np.flatnonzero(counts)
+                        neighbors = neighbors[
+                            self._legal_table[offset, neighbors, token] == 2
+                        ]
+                        for raw_neighbor in neighbors:
+                            neighbor = int(raw_neighbor)
+                            packed_key = (
+                                neighbor * vocab_width + token
+                            ) * lookahead + offset
+                            deltas[packed_key] += multiplier * int(counts[neighbor])
+
+    def _correct_internal_edges(
+        self,
+        instances: Sequence[int] | set[int],
+        correction: int,
+        deltas: Counter[int],
+    ) -> None:
+        
+        by_anchor: dict[int, list[int]] = {}
+        for instance in instances:
+            by_anchor.setdefault(self.anchors[instance], []).append(
+                self.tokens[instance]
+            )
+        vocab_width = self.max_vocab_size
+        lookahead = self.lookahead
+        for anchor, left_tokens in by_anchor.items():
+            for offset in range(1, self.lookahead):
+                right_tokens = by_anchor.get(anchor + offset)
+                if right_tokens is None:
+                    continue
+                for left in left_tokens:
+                    for right in right_tokens:
+                        if self._legal_table[offset, left, right] == 2:
+                            packed_key = (
+                                left * vocab_width + right
+                            ) * lookahead + offset
+                            deltas[packed_key] += correction
+
+    def _apply_deltas(self, deltas: Counter[int], selected: Rule) -> None:
+        
+        counts = self.counts
+        self_versions = self.self_versions
+        heap = self.heap
+        updates = 0
+        vocab_width = self.max_vocab_size
+        lookahead = self.lookahead
+        selected_key = (selected[0] * vocab_width + selected[1]) * lookahead + selected[
+            2
+        ]
+        for packed_key, delta in deltas.items():
+            previous = counts.get(packed_key, 0)
+            count = previous + delta
+            if count < 0:
+                raise RuntimeError("temporal edge counter became negative")
+
+
+            pair = packed_key // lookahead
+            is_self = pair % (vocab_width + 1) == 0
+            if is_self:
+                version = self_versions.get(packed_key, 0) + 1
+                self_versions[packed_key] = version
+                self.self_cache.pop(packed_key, None)
+            else:
+                version = 0
+            if count:
+                counts[packed_key] = count
+                if previous == 0 or packed_key == selected_key:
+                    pair, offset = divmod(packed_key, lookahead)
+                    left, right = divmod(pair, vocab_width)
+                    heapq.heappush(heap, (-count, left, right, offset, version, False))
+            else:
+                counts.pop(packed_key, None)
+            updates += abs(delta)
+        self.statistics["counter_updates"] += updates
+
+    def commit(self, key: Rule, matches: Sequence[tuple[int, int]]) -> None:
+        left, right, offset = key
+        pattern, masks = _merge_pattern(
+            self.patterns[left],
+            self.patterns[right],
+            offset,
+            self.lookahead,
+            self.spatial,
+        )
+        child = len(self.patterns)
+        self.patterns.append(pattern)
+        self.spans.append(len(masks))
+        self.masks.append(masks)
+        self.occurrences.append({})
+        self.merges.append(key)
+        self._mask_table[child, : len(masks)] = masks
+        self._initialize_legality(child)
+
+        removed = {instance for pair in matches for instance in pair}
+        if len(removed) != 2 * len(matches):
+            raise RuntimeError("selected temporal matches overlap")
+        deltas: Counter[int] = Counter()
+        self._accumulate_incident(removed, -1, deltas)
+        self._correct_internal_edges(removed, 1, deltas)
+
+        for instance in removed:
+            token = self.tokens[instance]
+            anchor = self.anchors[instance]
+            self.member[anchor, self.slots[instance]] = -1
+            self._active_count -= 1
+            self.occupied[anchor] = int(self.occupied[anchor]) & ~(
+                1 << self.slots[instance]
+            )
+            del self.occurrences[token][anchor]
+
+        children = [
+            self._new_instance(child, self.anchors[left_instance])
+            for left_instance, _ in matches
+        ]
+        self._accumulate_incident(children, 1, deltas)
+        self._correct_internal_edges(children, -1, deltas)
+        self._apply_deltas(deltas, key)
+
+    @property
+    def active_count(self) -> int:
+        return self._active_count
+
+
+def _prepare_episodes(
+    episodes: Iterable[np.ndarray], spatial: SpatialVocabulary
+) -> Sequence[np.ndarray]:
+    if getattr(episodes, "_actioncodec2_validated", False):
+        if not isinstance(episodes, Sequence) or len(episodes) == 0:
+            raise ValueError("validated temporal corpus must be a non-empty sequence")
+        return episodes
+    prepared: list[np.ndarray] = []
+    for episode in episodes:
+        values = np.asarray(episode)
+        if values.dtype.kind not in {"i", "u"}:
+            raise ValueError("episodes must contain integer cell indices")
+        _validate_episode(values, spatial)
+        prepared.append(np.ascontiguousarray(values))
+    if not prepared or sum(len(episode) for episode in prepared) == 0:
+        raise ValueError("temporal training requires at least one non-empty episode")
+    return prepared
+
+
+def _train_temporal_python(
+    episodes: Iterable[np.ndarray],
+    spatial: SpatialVocabulary,
+    *,
+    vocab_size: int,
+    lookahead: int,
+    progress: bool = False,
+) -> tuple[TemporalVocabulary, dict[str, object]]:
+    
+    prepared = _prepare_episodes(episodes, spatial)
+    if vocab_size < spatial.vocab_size:
+        raise ValueError(
+            f"vocab_size {vocab_size} is below the {spatial.vocab_size} spatial tokens"
+        )
+    trainer = _SparseTemporalTrainer(prepared, spatial, lookahead, vocab_size)
+    length = trainer.initial_count
+    for step in range(vocab_size - spatial.vocab_size):
+        winner = trainer.best()
+        if winner is None:
+            break
+        key, matches = winner
+        if not matches:
+            break
+        trainer.commit(key, matches)
+        length -= len(matches)
+        if progress and step % 64 == 0:
+            print(
+                f"  temporal merge {step:>5}  tokens/action {length / trainer.action_count:.4f}",
+                flush=True,
+            )
+    if length != trainer.active_count:
+        raise RuntimeError("temporal token accounting disagrees with active tiling")
+    vocabulary = TemporalVocabulary(spatial, lookahead, tuple(trainer.merges))
+    report: dict[str, object] = {
+        "episodes": trainer.episode_count,
+        "actions": trainer.action_count,
+        "lookahead": lookahead,
+        "spatial_vocab_size": spatial.vocab_size,
+        "merges": len(trainer.merges),
+        "vocab_size": vocabulary.vocab_size,
+        "tokens_per_action_initial": trainer.initial_count / trainer.action_count,
+        "tokens_per_action": length / trainer.action_count,
+        "compression": trainer.initial_count / length,
+        "trainer": "sparse_exact",
+        **{key: int(value) for key, value in trainer.statistics.items()},
+    }
+    return vocabulary, report
+
+
+def _flatten_instances_native(
+    episodes: Sequence[np.ndarray],
+    spatial: SpatialVocabulary,
+    lookahead: int,
+    threads: int,
+) -> tuple[Iterator[tuple[np.ndarray, np.ndarray]], int, int]:
+    
+    if getattr(episodes, "_actioncodec2_validated", False):
+        return _flatten_cell_corpus(episodes, spatial, lookahead, threads)
+    actions = sum(len(episode) for episode in episodes)
+    total_anchors = actions + len(episodes) * lookahead
+    max_batch_actions = 1_000_000
+    merges = np.asarray(spatial.merges, dtype=np.int32).reshape(-1, 2)
+
+    def generate() -> Iterator[tuple[np.ndarray, np.ndarray]]:
+        pending: list[np.ndarray] = []
+        pending_anchors: list[np.ndarray] = []
+        pending_actions = 0
+        base = 0
+
+        def encode() -> tuple[np.ndarray, np.ndarray]:
+            codes = np.concatenate(pending, axis=0).astype(np.int32, copy=False)
+            row_anchors = np.concatenate(pending_anchors)
+            tokens, anchors = require_native().spatial_encode_instances(
+                np.ascontiguousarray(codes),
+                np.ascontiguousarray(row_anchors),
+                [int(count) for count in spatial.bins],
+                np.ascontiguousarray(merges),
+                int(threads),
+            )
+            return np.asarray(tokens, dtype=np.int32), np.asarray(
+                anchors, dtype=np.int64
+            )
+
+        for episode in episodes:
+            length = len(episode)
+            pending.append(episode)
+            pending_anchors.append(np.arange(base, base + length, dtype=np.int64))
+            pending_actions += length
+            base += length + lookahead
+            if pending_actions >= max_batch_actions:
+                yield encode()
+                pending.clear()
+                pending_anchors.clear()
+                pending_actions = 0
+        if pending:
+            yield encode()
+
+    return generate(), total_anchors, actions
+
+
+def _flatten_cell_corpus(
+    episodes: Sequence[np.ndarray],
+    spatial: SpatialVocabulary,
+    lookahead: int,
+    threads: int,
+) -> tuple[Iterator[tuple[np.ndarray, np.ndarray]], int, int]:
+    
+    actions = sum(len(codes) for codes in episodes.chunks if codes is not None)
+    total_anchors = actions + len(episodes) * lookahead
+    merges = np.asarray(spatial.merges, dtype=np.int32).reshape(-1, 2)
+    chunks = episodes.chunks
+    offsets_by_chunk = episodes.offsets
+
+    def generate() -> Iterator[tuple[np.ndarray, np.ndarray]]:
+        base = 0
+        for chunk_index, (codes, offsets) in enumerate(
+            zip(chunks, offsets_by_chunk, strict=True)
+        ):
+            if codes is None:
+                raise RuntimeError("cell corpus chunk has already been consumed")
+            lengths = np.diff(offsets)
+            row_anchors = (
+                base
+                + np.arange(len(codes), dtype=np.int64)
+                + np.repeat(
+                    np.arange(len(lengths), dtype=np.int64) * lookahead, lengths
+                )
+            )
+            tokens, anchors = require_native().spatial_encode_instances(
+                np.ascontiguousarray(codes),
+                row_anchors,
+                [int(count) for count in spatial.bins],
+                np.ascontiguousarray(merges),
+                int(threads),
+            )
+            episodes.release_chunk(chunk_index)
+            yield (
+                np.asarray(tokens, dtype=np.int32),
+                np.asarray(anchors, dtype=np.int64),
+            )
+            base += len(codes) + len(lengths) * lookahead
+
+    return generate(), total_anchors, actions
+
+
+def train_temporal(
+    episodes: Iterable[np.ndarray],
+    spatial: SpatialVocabulary,
+    *,
+    vocab_size: int,
+    lookahead: int,
+    backend: str = "auto",
+    progress: bool = False,
+    threads: int = 0,
+) -> tuple[TemporalVocabulary, dict[str, object]]:
+    "Fit rooted temporal Set-BPE on top of a frozen spatial vocabulary."
+    prepared = _prepare_episodes(episodes, spatial)
+    if resolve_backend(backend) == "python":
+        return _train_temporal_python(
+            prepared,
+            spatial,
+            vocab_size=vocab_size,
+            lookahead=lookahead,
+            progress=progress,
+        )
+    episode_count = len(prepared)
+    instance_chunks, total_anchors, actions = _flatten_instances_native(
+        prepared, spatial, lookahead, threads
+    )
+    merges, report = require_native().train_temporal(
+        instance_chunks,
+        int(total_anchors),
+        np.ascontiguousarray(spatial.support, dtype=np.uint64),
+        np.ascontiguousarray(spatial.anchor, dtype=np.int32),
+        int(spatial.dimension),
+        int(lookahead),
+        int(vocab_size),
+        int(actions),
+        int(threads),
+    )
+    vocabulary = TemporalVocabulary(
+        spatial,
+        int(lookahead),
+        tuple(tuple(int(value) for value in rule) for rule in merges),
+    )
+    payload = dict(report)
+    payload["episodes"] = episode_count
+    return vocabulary, payload

runtime/training/__init__.py

@@ -0,0 +1 @@
+"""Internal training components for ActionCodec2."""

runtime/training/fitting.py

@@ -0,0 +1,179 @@
+"""Replayable, bounded source staging for the public ActionCodec2.fit interface."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from contextlib import ExitStack
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import numpy as np
+import torch
+
+from ..physical.boundary import bootstrap_second_order_trajectory
+from ..routing.routing import ActionCodec2Router
+from ..frontend.tokenizer import _numpy
+from .training import ProfileTrainer
+from ..physical.trajectory import ActiveTrajectory
+
+
+class TrajectorySpool:
+    "Stage canonical episodes in two sequential files, without retaining source data."
+
+    def __init__(self, directory):
+        self.directory = Path(directory)
+        self.counts = {}
+        self._stack = ExitStack()
+        self._writers = {}
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return self._stack.__exit__(*exc)
+
+    def append(self, profile, trajectory):
+        if profile not in self._writers:
+            self._writers[profile] = self._stack.enter_context(
+                (self.directory / f"{profile}.npy").open("wb")
+            )
+        stream = self._writers[profile]
+        for value in (
+            trajectory.values,
+            trajectory.active_dims,
+            []
+            if trajectory.previous_first_order is None
+            else trajectory.previous_first_order,
+        ):
+            np.save(stream, np.asarray(value), allow_pickle=False)
+        self.counts[profile] = self.counts.get(profile, 0) + 1
+
+    def trajectories(self, profile):
+        self._writers[profile].flush()
+        with (self.directory / f"{profile}.npy").open("rb") as stream:
+            for _ in range(self.counts[profile]):
+                values = np.load(stream, allow_pickle=False)
+                dims = tuple(int(d) for d in np.load(stream, allow_pickle=False))
+                previous = np.load(stream, allow_pickle=False)
+                yield ActiveTrajectory(
+                    values,
+                    dims,
+                    previous_first_order=previous if previous.size else None,
+                )
+
+
+class ActionCodec2Fitter:
+    "Route user layouts and fit replacement profiles without mutating the caller."
+
+    def __init__(self, codec, *, bootstrap_context=False):
+        if not isinstance(bootstrap_context, bool):
+            raise TypeError("bootstrap_context must be a boolean")
+        self.codec = codec
+        self.router = codec.action_tokenizer
+        self.bootstrap_context = bootstrap_context
+
+    def _route(self, record):
+        unknown = set(record) - {
+            "actions",
+            "action_space",
+            "fps",
+            "current_state",
+            "previous_first_order",
+        }
+        if unknown:
+            raise ValueError(f"unknown training record fields: {sorted(unknown)}")
+        if "actions" not in record:
+            raise ValueError("training record requires an 'actions' array")
+        preset = self.router.preset(
+            record.get("action_space", self.codec.action_space.name)
+        )
+        values = _numpy(torch.as_tensor(record["actions"]))
+        if values.ndim == 2:
+            values = values[None]
+        if values.ndim != 3 or values.shape[0] == 0 or values.shape[1] == 0:
+            raise ValueError(
+                "training actions must have nonempty shape (T,D) or (B,T,D)"
+            )
+        current = _numpy(record.get("current_state"))
+        if preset.input == "absolute" and current is None:
+            raise ValueError(
+                f"absolute action space {preset.name!r} requires current_state(B,D)"
+            )
+        if preset.input == "delta" and current is not None:
+            raise ValueError(f"delta action space {preset.name!r}: omit current_state")
+        previous = self.codec._numpy_boundary(record.get("previous_first_order"))
+        kwargs = dict(
+            preset=preset.name,
+            fps=self.codec._source_fps(record.get("fps"), preset),
+            current_state=current,
+        )
+        if not self.bootstrap_context:
+            return self.router.route_trajectories(
+                values, previous_first_order=previous, **kwargs
+            )
+        if previous is not None:
+            raise ValueError(
+                "bootstrap_context and previous_first_order are mutually exclusive"
+            )
+        canonical = preset.canonicalize(
+            values, source_hz=kwargs["fps"], current_state=current
+        )
+        routed = {}
+        for component in preset.components:
+            processor = self.router.profiles[component.space].processor
+            trajectories = canonical[component.name]
+            if processor.requires_previous_first_order:
+                trajectories = [
+                    bootstrap_second_order_trajectory(t, processor.config)
+                    for t in trajectories
+                ]
+            routed.setdefault(component.space, []).extend(trajectories)
+        return routed
+
+    def fit(self, episodes, *, work_dir=None, metadata=None, **options):
+        """Fit observed profiles from arrays or records, replaying staged episodes per profile."""
+        metadata = {k: v for k, v in (metadata or {}).items() if v is not None}
+        if isinstance(episodes, (np.ndarray, torch.Tensor, Mapping)):
+            episodes = (episodes,)
+        reports = {}
+        processors = {
+            name: runtime.processor for name, runtime in self.router.profiles.items()
+        }
+        records = 0
+        with TemporaryDirectory(prefix="actioncodec2-fit-", dir=work_dir) as directory:
+            with TrajectorySpool(directory) as spool:
+                for episode in episodes:
+                    record = (
+                        dict(episode)
+                        if isinstance(episode, Mapping)
+                        else {"actions": episode}
+                    )
+                    duplicates = set(record).intersection(metadata)
+                    if duplicates:
+                        raise ValueError(
+                            f"training arguments provided twice: {sorted(duplicates)}"
+                        )
+                    record.update(metadata)
+                    for profile, trajectories in self._route(record).items():
+                        for trajectory in trajectories:
+                            spool.append(profile, trajectory)
+                    records += 1
+                if not spool.counts:
+                    raise ValueError("fit requires at least one nonempty episode")
+                for name in spool.counts:
+                    processors[name], reports[name] = ProfileTrainer(
+                        processors[name].config
+                    ).fit(spool.trajectories(name), **options)
+        router = ActionCodec2Router.from_processors(
+            processors,
+            token_budgets={
+                name: runtime.spec.token_budget
+                for name, runtime in self.router.profiles.items()
+            },
+            presets=list(self.router.action_spaces.values()),
+        )
+        return router, {
+            "records": records,
+            "bootstrap_context": self.bootstrap_context,
+            "profiles": reports,
+        }

runtime/training/training.py

@@ -0,0 +1,698 @@
+"Whole-trajectory primitive construction and BPE fitting."
+
+from __future__ import annotations
+
+import math
+import time
+from bisect import bisect_right
+from collections import defaultdict
+from collections.abc import Iterable, Sequence
+
+import numpy as np
+
+from ..common._validation import broadcast_vector
+from ..tokenization.bpe import BPESerializer, SetBPESerializer
+from ..tokenization.bpe_training import train_bpe
+from ..physical.configuration import ActionCodec2Config, ConfigError
+from ..physical.physical_codec import PhysicalCodec
+from ..physical.physical_processor import ActionCodec2Processor
+from ..physical.primitives import PrimitiveStore
+from ..tokenization.setbpe_spatial import aggregate_records
+from ..tokenization.setbpe_spatial_training import train_spatial
+from ..tokenization.setbpe_temporal_training import train_temporal
+from ..physical.trajectory import (
+    TrajectoryLike,
+    prepare_trajectory,
+    trajectory_boundary,
+)
+
+
+def _zero_anchored_grid(
+    lower: np.float32, upper: np.float32, spacing: np.float32
+) -> np.ndarray:
+    
+    below = int(np.ceil(-lower / spacing))
+    above = int(np.ceil(upper / spacing))
+    negative = np.linspace(lower, np.float32(0.0), below + 1, dtype=np.float32)[:-1]
+    positive = np.linspace(np.float32(0.0), upper, above + 1, dtype=np.float32)
+    return np.concatenate((negative, positive))
+
+
+def _additive_axis(
+    lower: np.float32,
+    upper: np.float32,
+    distortion_limit: np.float32,
+    *,
+    zero_primitive: bool,
+) -> np.ndarray:
+    
+    width = np.float32(upper - lower)
+    if width == 0.0:
+        return np.asarray([lower], dtype=np.float32)
+    spacing = np.float32(2.0) * distortion_limit
+    if zero_primitive and lower < 0.0 < upper:
+        return _zero_anchored_grid(lower, upper, spacing)
+    count = 1 + int(np.ceil(width / spacing))
+    return np.linspace(lower, upper, count, dtype=np.float32)
+
+
+def build_primitives(config: ActionCodec2Config) -> PrimitiveStore:
+    "Derive primitive arrays and force an exact zero on every axis."
+    if config.train is None:
+        raise ConfigError("config.train is required to build primitives")
+    output: list[np.ndarray | None] = [None] * config.physical.input_dim
+    for component in config.physical.components.values():
+        width = len(component.dims)
+        if component.space == "additive":
+            domain = component.constraints[f"order_{component.primitive_order}"]
+            lower = broadcast_vector(
+                domain.minimum, width, dtype=np.dtype(np.float32), name="minimum"
+            )
+            upper = broadcast_vector(
+                domain.maximum, width, dtype=np.dtype(np.float32), name="maximum"
+            )
+            epsilon = broadcast_vector(
+                component.distortion_limit,
+                width,
+                dtype=np.dtype(np.float32),
+                name="distortion_limit",
+            )
+            if component.primitive_order == 2:
+
+                lower = lower - 2 * epsilon
+                upper = upper + 2 * epsilon
+            axes = [
+                _additive_axis(
+                    lower[index],
+                    upper[index],
+                    epsilon[index],
+                    zero_primitive=True,
+                )
+                for index in range(width)
+            ]
+        else:
+            domain = component.constraints[f"order_{component.primitive_order}"]
+            radius_dtype = (
+                np.float64
+                if component.representation == "rotation_vector"
+                else np.float32
+            )
+            lower = broadcast_vector(
+                domain.minimum, width, dtype=np.dtype(radius_dtype), name="minimum"
+            )
+            upper = broadcast_vector(
+                domain.maximum, width, dtype=np.dtype(radius_dtype), name="maximum"
+            )
+            corner = np.maximum(np.abs(lower), np.abs(upper))
+            source_radius = (
+                float(np.linalg.norm(corner))
+                if component.representation == "rotation_vector"
+                else float(np.sum(corner, dtype=np.float32))
+            )
+            source_radius = min(math.pi, source_radius)
+            epsilon = float(component.distortion_limit)
+            allowance = (3 if component.primitive_order == 2 else 1) * epsilon
+            cover_radius = float(min(math.pi, source_radius + allowance))
+            maximum_spacing = 2.0 * epsilon / math.sqrt(3.0)
+            count = int(math.ceil(2.0 * cover_radius / maximum_spacing)) + 1
+            if count % 2 == 0:
+                count += 1
+            axis = np.linspace(-cover_radius, cover_radius, count, dtype=np.float64)
+            if count % 2 == 1:
+                axis[count // 2] = 0.0
+            axes = [axis.copy() for _ in range(width)]
+        for dimension, axis in zip(component.dims, axes, strict=True):
+            output[dimension] = axis
+    if any(axis is None for axis in output):
+        raise RuntimeError(
+            "internal error: primitive construction left an unassigned dimension"
+        )
+    store = PrimitiveStore([axis for axis in output if axis is not None])
+    missing_zero = [
+        dimension
+        for dimension, axis in enumerate(store.values)
+        if not np.any(np.asarray(axis) == 0)
+    ]
+    if missing_zero:
+        raise ConfigError(
+            "every fitted primitive axis must contain exact zero; missing dimension(s) "
+            f"{missing_zero}. Ensure each configured domain contains zero."
+        )
+    return store
+
+
+def _validate_component_support(
+    active_dims: tuple[int, ...], config: ActionCodec2Config, *, index: int
+) -> None:
+    active = set(active_dims)
+    for name, component in config.physical.components.items():
+        present = active.intersection(component.dims)
+        if component.space == "so3" and present and present != set(component.dims):
+            raise ValueError(
+                f"trajectory {index} activates only part of SO(3) component {name!r}"
+            )
+
+
+def _length_buckets(
+    pending: Sequence[tuple[np.ndarray, tuple[int, ...], np.ndarray | None]],
+    *,
+    maximum_ratio: float = 1.25,
+) -> list[list[int]]:
+    
+    ordered = sorted(range(len(pending)), key=lambda index: len(pending[index][0]))
+    buckets: list[list[int]] = []
+    current: list[int] = []
+    shortest = 0
+    for index in ordered:
+        length = len(pending[index][0])
+        if current and length > shortest * maximum_ratio:
+            buckets.append(current)
+            current = []
+        if not current:
+            shortest = length
+        current.append(index)
+    if current:
+        buckets.append(current)
+    return buckets
+
+
+class _CellCorpus(Sequence[np.ndarray]):
+    
+
+    _actioncodec2_validated = True
+
+    def __init__(self, chunks: list[np.ndarray], offsets: list[np.ndarray]) -> None:
+        self.chunks: list[np.ndarray | None] = list(chunks)
+        self.offsets = tuple(offsets)
+        counts = np.asarray([len(value) - 1 for value in offsets], dtype=np.int64)
+        self._episode_ends = np.cumsum(counts)
+
+    def __len__(self) -> int:
+        return int(self._episode_ends[-1]) if len(self._episode_ends) else 0
+
+    def __getitem__(self, index: int) -> np.ndarray:
+        if not isinstance(index, int):
+            raise TypeError("cell corpus indices must be integers")
+        if index < 0:
+            index += len(self)
+        if not 0 <= index < len(self):
+            raise IndexError(index)
+        chunk = bisect_right(self._episode_ends, index)
+        previous = 0 if chunk == 0 else int(self._episode_ends[chunk - 1])
+        local = index - previous
+        start, stop = self.offsets[chunk][local : local + 2]
+        values = self.chunks[chunk]
+        if values is None:
+            raise RuntimeError("cell corpus chunk has already been consumed")
+        return values[int(start) : int(stop)]
+
+    def __iter__(self):
+        for chunk, offsets in zip(self.chunks, self.offsets, strict=True):
+            if chunk is None:
+                raise RuntimeError("cell corpus chunk has already been consumed")
+            for start, stop in zip(offsets[:-1], offsets[1:], strict=True):
+                yield chunk[int(start) : int(stop)]
+
+    def release_chunk(self, index: int) -> None:
+        """Release a replayed chunk while retaining compact episode metadata."""
+        self.chunks[index] = None
+
+
+def _quantize_pending_batch(
+    pending: Sequence[tuple[np.ndarray, tuple[int, ...], np.ndarray | None]],
+    physical: PhysicalCodec,
+    cell_dtype: type[np.signedinteger],
+) -> list[np.ndarray]:
+    
+    result: list[np.ndarray | None] = [None] * len(pending)
+    dimension = physical.config.physical.input_dim
+    for indices in _length_buckets(pending):
+        length = max(len(pending[index][0]) for index in indices)
+        batch = np.zeros((len(indices), length, dimension), dtype=np.float32)
+        active_by_item: list[tuple[int, ...]] = []
+        for local, index in enumerate(indices):
+            trajectory, active_dims, _ = pending[index]
+            item = batch[local, : len(trajectory)]
+            item[:, active_dims] = trajectory
+            active_by_item.append(active_dims)
+        boundaries = [pending[index][2] for index in indices]
+        previous = (
+            None
+            if all(value is None for value in boundaries)
+            else np.stack(
+                [
+                    np.zeros(dimension, dtype=np.float32) if value is None else value
+                    for value in boundaries
+                ]
+            )
+        )
+        encoded = physical.encode_batch(batch, previous_first_order=previous).astype(
+            cell_dtype, copy=False
+        )
+        for local, index in enumerate(indices):
+            item_length = len(pending[index][0])
+            dense = np.full((item_length, dimension), -1, dtype=cell_dtype)
+            dense[:, active_by_item[local]] = encoded[local][
+                :item_length, active_by_item[local]
+            ]
+            result[index] = dense
+    if any(value is None for value in result):
+        raise RuntimeError("internal error: trajectory batch was not fully quantized")
+    return [value for value in result if value is not None]
+
+
+def _quantize_trajectories(
+    trajectories: Iterable[TrajectoryLike],
+    physical: PhysicalCodec,
+    *,
+    batch_size: int,
+    max_cell_bytes: int | None,
+) -> tuple[_CellCorpus, int, int, dict[int, int]]:
+    
+    if batch_size < 1:
+        raise ValueError("batch_size must be positive")
+    cell_chunks: list[np.ndarray] = []
+    offset_chunks: list[np.ndarray] = []
+    cell_parts: list[np.ndarray] = []
+    cell_lengths: list[int] = []
+    chunk_actions = 0
+    action_count = 0
+    active_value_count = 0
+    arity_counts: dict[int, int] = defaultdict(int)
+    source_index = 0
+    retained_cell_bytes = 0
+    cell_dtype = np.int16 if max(physical.bins) <= np.iinfo(np.int16).max else np.int32
+    iterator = iter(trajectories)
+
+    def flush_cells() -> None:
+        nonlocal chunk_actions, retained_cell_bytes
+        if not cell_parts:
+            return
+        chunk = np.concatenate(cell_parts, axis=0)
+        projected = retained_cell_bytes + chunk.nbytes
+        if max_cell_bytes is not None and projected > max_cell_bytes:
+            raise MemoryError(
+                "quantized ActionCodec2 corpus would retain at least "
+                f"{projected / 2**30:.2f} GiB, exceeding the configured "
+                f"{max_cell_bytes / 2**30:.2f} GiB limit; use stratified fitting, "
+                "lower coverage, or explicitly raise --max-cell-memory-gib"
+            )
+        cell_chunks.append(chunk)
+        retained_cell_bytes = projected
+        offset_chunks.append(
+            np.concatenate(([0], np.cumsum(cell_lengths, dtype=np.int64)))
+        )
+        cell_parts.clear()
+        cell_lengths.clear()
+        chunk_actions = 0
+
+    while True:
+        pending: list[tuple[np.ndarray, tuple[int, ...], np.ndarray | None]] = []
+        for _ in range(batch_size):
+            try:
+                raw = next(iterator)
+            except StopIteration:
+                break
+            trajectory, active_dims = prepare_trajectory(
+                raw,
+                index=source_index,
+                dimension=physical.config.physical.input_dim,
+                dtype=np.float32,
+            )
+            _validate_component_support(
+                active_dims, physical.config, index=source_index
+            )
+            source_index += 1
+            action_count += len(trajectory)
+            active_value_count += len(trajectory) * len(active_dims)
+            arity_counts[len(active_dims)] += 1
+            pending.append(
+                (
+                    trajectory,
+                    active_dims,
+                    trajectory_boundary(raw, physical.config, active_dims),
+                )
+            )
+        if not pending:
+            break
+
+        for value in _quantize_pending_batch(pending, physical, cell_dtype):
+            cell_parts.append(value)
+            cell_lengths.append(len(value))
+            chunk_actions += len(value)
+        if chunk_actions >= 1_000_000:
+            flush_cells()
+    flush_cells()
+    cells = _CellCorpus(cell_chunks, offset_chunks)
+    if not cells:
+        raise ValueError("training requires at least one complete trajectory")
+    return cells, action_count, active_value_count, dict(sorted(arity_counts.items()))
+
+
+def _aggregate_trajectory_records(
+    cells: Sequence[np.ndarray], bins: Sequence[int], action_count: int
+) -> tuple[np.ndarray, np.ndarray]:
+    
+    del action_count
+    dimension = len(tuple(bins))
+    widths = tuple(int(count).bit_length() for count in bins)
+    if sum(widths) <= 64:
+        return _aggregate_packed_records(cells, bins, widths)
+    counts_by_row: dict[bytes, int] = defaultdict(int)
+    pending: list[np.ndarray] = []
+    pending_rows = 0
+    chunk_rows = 1_000_000
+
+    def flush() -> None:
+        nonlocal pending_rows
+        if not pending:
+            return
+        block = (
+            np.asarray(pending[0], dtype=np.int32)
+            if len(pending) == 1
+            else np.concatenate(pending, axis=0).astype(np.int32, copy=False)
+        )
+        unique, counts = aggregate_records(block, bins)
+        for row, count in zip(unique.astype(np.int32, copy=False), counts, strict=True):
+            counts_by_row[row.tobytes()] += int(count)
+        pending.clear()
+        pending_rows = 0
+
+    for trajectory in cells:
+        pending.append(np.asarray(trajectory, dtype=np.int32))
+        pending_rows += len(trajectory)
+        if pending_rows >= chunk_rows:
+            flush()
+    flush()
+    keys = sorted(counts_by_row)
+    records = np.frombuffer(b"".join(keys), dtype=np.int32).reshape(-1, dimension)
+    weights = np.fromiter(
+        (counts_by_row[key] for key in keys), dtype=np.int64, count=len(keys)
+    )
+    return records, weights
+
+
+def _aggregate_packed_records(
+    cells: Sequence[np.ndarray], bins: Sequence[int], widths: Sequence[int]
+) -> tuple[np.ndarray, np.ndarray]:
+    
+    counts_by_key: dict[int, int] = defaultdict(int)
+    pending: list[np.ndarray] = []
+    pending_rows = 0
+    chunk_rows = 1_000_000
+
+    def flush() -> None:
+        nonlocal pending_rows
+        if not pending:
+            return
+        block = pending[0] if len(pending) == 1 else np.concatenate(pending, axis=0)
+        keys = np.zeros(len(block), dtype=np.uint64)
+        shift = 0
+        for dimension, width in enumerate(widths):
+            encoded = np.asarray(block[:, dimension], dtype=np.int64) + 1
+            keys |= encoded.astype(np.uint64) << np.uint64(shift)
+            shift += width
+        unique, counts = np.unique(keys, return_counts=True)
+        for key, count in zip(unique, counts, strict=True):
+            counts_by_key[int(key)] += int(count)
+        pending.clear()
+        pending_rows = 0
+
+    for trajectory in cells:
+        pending.append(trajectory)
+        pending_rows += len(trajectory)
+        if pending_rows >= chunk_rows:
+            flush()
+    flush()
+
+    keys = np.fromiter(sorted(counts_by_key), dtype=np.uint64, count=len(counts_by_key))
+    records = np.empty((len(keys), len(tuple(bins))), dtype=np.int32)
+    shift = 0
+    for dimension, width in enumerate(widths):
+        mask = np.uint64((1 << width) - 1)
+        records[:, dimension] = ((keys >> np.uint64(shift)) & mask).astype(np.int32) - 1
+        shift += width
+    weights = np.fromiter(
+        (counts_by_key[int(key)] for key in keys), dtype=np.int64, count=len(keys)
+    )
+    return records, weights
+
+
+def _fit_report(
+    config: ActionCodec2Config,
+    primitives: PrimitiveStore,
+    codec: ActionCodec2Processor,
+    *,
+    trajectory_count: int,
+    actions: int,
+    active_values: int,
+    arity_counts: dict[int, int],
+    cell_dtype: str,
+    unique_records: int,
+    spatial_report: dict[str, object],
+    temporal_report: dict[str, object],
+    timestamps: tuple[float, float, float, float, float, float],
+) -> dict[str, object]:
+    started, primitive_done, quantized, aggregated, spatial_done, finished = timestamps
+    scheme = config.set_bpe.scheme
+    stages: dict[str, object] = (
+        {"bpe": temporal_report}
+        if scheme == "bpe"
+        else {"spatial": spatial_report, "temporal": temporal_report}
+    )
+    return {
+        "trajectories": trajectory_count,
+        "actions": actions,
+        "active_values": active_values,
+        "trajectory_arities": {str(key): value for key, value in arity_counts.items()},
+        "bpe_boundary": "complete_component_trajectory",
+        "bpe_training_domain": "quantized_primitive_cells",
+        "physical_boundary": (
+            "explicit_previous_first_order"
+            if codec.requires_previous_first_order
+            else "zero_position_identity_orientation"
+        ),
+        "component_primitive_orders": {
+            name: component.primitive_order
+            for name, component in config.physical.components.items()
+        },
+        "allow_cross_component_merge": config.set_bpe.allow_cross_component_merge,
+        "lookahead": config.set_bpe.lookahead,
+        "physical_bins": list(primitives.bins),
+        "cell_dtype": cell_dtype,
+        "unique_spatial_records": unique_records,
+        "primitive_atoms": sum(primitives.bins),
+        "tokenization_scheme": scheme,
+        **stages,
+        "vocab_size": codec.vocab_size,
+        "tokens_per_action": float(temporal_report["tokens_per_action"]),
+        "seconds": {
+            "primitives": primitive_done - started,
+            "quantize": quantized - primitive_done,
+            "aggregate": aggregated - quantized,
+            "spatial_train": spatial_done - aggregated,
+            "spatial": spatial_done - quantized,
+            "temporal": finished - spatial_done,
+            "total": finished - started,
+        },
+    }
+
+
+def _fit_set_bpe(
+    cells: Sequence[np.ndarray],
+    config: ActionCodec2Config,
+    primitives: PrimitiveStore,
+    actions: int,
+    *,
+    backend: str,
+    threads: int,
+    progress: bool,
+) -> tuple[SetBPESerializer, dict[str, object], dict[str, object], int, float, float]:
+    records, weights = _aggregate_trajectory_records(cells, primitives.bins, actions)
+    aggregated = time.perf_counter()
+    bpe = config.train.bpe if config.train is not None else None
+    assert bpe is not None
+    spatial, spatial_report = train_spatial(
+        records,
+        weights,
+        primitives.bins,
+        vocab_size=bpe.spatial_vocab_size,
+        backend=backend,
+        threads=threads,
+        progress=progress,
+    )
+    spatial_done = time.perf_counter()
+    vocabulary, temporal_report = train_temporal(
+        cells,
+        spatial,
+        vocab_size=bpe.vocab_size,
+        lookahead=config.set_bpe.lookahead,
+        backend=backend,
+        threads=threads,
+        progress=progress,
+    )
+    serializer = SetBPESerializer(
+        bins=primitives.bins,
+        lookahead=config.set_bpe.lookahead,
+        spatial_merges=spatial.merges,
+        temporal_merges=vocabulary.merges,
+    )
+    return (
+        serializer,
+        spatial_report,
+        temporal_report,
+        len(records),
+        aggregated,
+        spatial_done,
+    )
+
+
+def _fit_bpe(
+    cells: Sequence[np.ndarray],
+    config: ActionCodec2Config,
+    primitives: PrimitiveStore,
+    *,
+    backend: str,
+    threads: int,
+    progress: bool,
+) -> tuple[BPESerializer, dict[str, object], dict[str, object], int, float, float]:
+    
+    started = time.perf_counter()
+    bpe = config.train.bpe if config.train is not None else None
+    assert bpe is not None
+    vocabulary, report = train_bpe(
+        cells,
+        primitives.bins,
+        vocab_size=bpe.vocab_size,
+        max_token_cells=config.set_bpe.lookahead * config.physical.input_dim,
+        backend=backend,
+        threads=threads,
+        progress=progress,
+    )
+    serializer = BPESerializer(
+        bins=primitives.bins,
+        lookahead=config.set_bpe.lookahead,
+        merges=vocabulary.merges,
+    )
+    return serializer, {}, report, 0, started, started
+
+
+def _validate_fit_options(
+    config: ActionCodec2Config, max_cell_bytes: int | None
+) -> None:
+    if config.train is None:
+        raise ConfigError("config.train is required for fitting")
+    if max_cell_bytes is not None and (
+        isinstance(max_cell_bytes, bool)
+        or not isinstance(max_cell_bytes, int)
+        or max_cell_bytes < 1
+    ):
+        raise ValueError("max_cell_bytes must be a positive integer or None")
+    if config.set_bpe.allow_cross_component_merge:
+        raise ConfigError(
+            "allow_cross_component_merge=true requires the future multi-component "
+            "corpus representation; v1 fitting supports the default isolated boundary only"
+        )
+    if config.set_bpe.scheme == "bpe" and config.train.bpe.spatial_vocab_size != (
+        config.train.bpe.vocab_size
+    ):
+        raise ConfigError(
+            "set_bpe.scheme=bpe has a single merge stage; set "
+            "train.bpe.spatial_vocab_size equal to train.bpe.vocab_size to make the "
+            "unused split explicit"
+        )
+
+
+class ProfileTrainer:
+    "Internal whole-trajectory fitter for one physical profile."
+
+    def __init__(self, config: ActionCodec2Config) -> None:
+        self.config = config
+
+    def fit(
+        self,
+        trajectories: Iterable[TrajectoryLike],
+        *,
+        backend: str = "auto",
+        threads: int = 0,
+        batch_size: int = 256,
+        progress: bool = False,
+        max_cell_bytes: int | None = None,
+    ) -> tuple[ActionCodec2Processor, dict[str, object]]:
+        "Fit primitives and the configured tokenization scheme on whole trajectories."
+        config = self.config
+        _validate_fit_options(config, max_cell_bytes)
+        started = time.perf_counter()
+        primitives = build_primitives(config)
+        primitive_done = time.perf_counter()
+
+        atoms = sum(primitives.bins)
+        bpe = config.train.bpe
+        if bpe.spatial_vocab_size < atoms:
+            raise ConfigError(
+                f"train.bpe.spatial_vocab_size must be at least the {atoms} primitive atoms"
+            )
+
+        physical = PhysicalCodec(config, primitives)
+        cells, actions, active_values, arity_counts = _quantize_trajectories(
+            trajectories,
+            physical,
+            batch_size=batch_size,
+            max_cell_bytes=max_cell_bytes,
+        )
+        trajectory_count = len(cells)
+        first_cell_dtype = str(cells[0].dtype)
+        quantized = time.perf_counter()
+
+        if config.set_bpe.scheme == "bpe":
+            fitted = _fit_bpe(
+                cells,
+                config,
+                primitives,
+                backend=backend,
+                threads=threads,
+                progress=progress,
+            )
+        else:
+            fitted = _fit_set_bpe(
+                cells,
+                config,
+                primitives,
+                actions,
+                backend=backend,
+                threads=threads,
+                progress=progress,
+            )
+        (
+            serializer,
+            spatial_report,
+            temporal_report,
+            unique_records,
+            aggregated,
+            spatial_done,
+        ) = fitted
+        codec = ActionCodec2Processor(config, primitives, serializer)
+        finished = time.perf_counter()
+
+        report = _fit_report(
+            config,
+            primitives,
+            codec,
+            trajectory_count=trajectory_count,
+            actions=actions,
+            active_values=active_values,
+            arity_counts=arity_counts,
+            cell_dtype=first_cell_dtype,
+            unique_records=unique_records,
+            spatial_report=spatial_report,
+            temporal_report=temporal_report,
+            timestamps=(
+                started,
+                primitive_done,
+                quantized,
+                aggregated,
+                spatial_done,
+                finished,
+            ),
+        )
+        return codec, report

setup.py

@@ -0,0 +1,17 @@
+from setuptools import setup
+from pybind11.setup_helpers import Pybind11Extension, build_ext
+
+native = "actioncodec2_kernels"
+setup(
+    ext_modules=[Pybind11Extension(
+        "actioncodec2_kernels._actioncodec2_native",
+        sources=[f"{native}/{name}.cpp" for name in (
+            "module", "physical", "so3", "setbpe", "resample", "reconstruct", "grammar"
+        )],
+        include_dirs=[native],
+        depends=[f"{native}/{name}.hpp" for name in ("parallel", "quaternion")],
+        extra_compile_args=["-O3", "-fvisibility=hidden", "-ffp-contract=off"],
+        cxx_std=17,
+    )],
+    cmdclass={"build_ext": build_ext},
+)

variants/extended-1st-10mm-16k/config.json

@@ -0,0 +1,4 @@
+{
+  "model_type": "actioncodec2",
+  "processor_class": "ActionCodec2"
+}

variants/extended-1st-10mm-16k/processor_config.json

@@ -0,0 +1,11 @@
+{
+  "processor_class": "ActionCodec2",
+  "action_space": "single_eef_delta",
+  "fitted_profiles": [
+    "eef",
+    "joint"
+  ],
+  "auto_map": {
+    "AutoProcessor": "processing_actioncodec2.ActionCodec2"
+  }
+}

variants/extended-1st-10mm-16k/profiles/eef/config.json

@@ -0,0 +1,4 @@
+{
+  "model_type": "actioncodec2_unified",
+  "processor_class": "ActionCodec2Processor"
+}

variants/extended-1st-10mm-16k/profiles/eef/config.yaml

@@ -0,0 +1,74 @@
+model_type: actioncodec2_unified
+config_version: 1
+physical:
+  input_dim: 7
+  components:
+    translation_m:
+      dims:
+        start: 0
+        stop: 3
+      space: additive
+      input_order: 0
+      primitive_order: 1
+      input_transform:
+        scale: 1.0
+        clip: false
+      constraints:
+        order_0:
+          min: -2.0
+          max: 2.0
+        order_1:
+          min: -0.08
+          max: 0.08
+      distortion_limit: 0.01
+      primitive_selection: smooth
+    orientation_so3:
+      dims:
+        start: 3
+        stop: 6
+      space: so3
+      input_order: 0
+      primitive_order: 1
+      input_transform:
+        scale: 1.0
+        clip: false
+      constraints:
+        order_0:
+          min: -3.141592653589793
+          max: 3.141592653589793
+        order_1:
+          min: -0.25
+          max: 0.25
+      distortion_limit: 0.04
+      primitive_selection: smooth
+      representation: rotation_vector
+      multiplication: right
+    gripper_open_command:
+      dims:
+      - 6
+      space: additive
+      input_order: 0
+      primitive_order: 0
+      input_transform:
+        scale: 1.0
+        clip: true
+      constraints:
+        order_0:
+          min: 0.0
+          max: 1.0
+      distortion_limit: 0.5
+      primitive_selection: nearest
+set_bpe:
+  lookahead: 8
+  allow_cross_component_merge: false
+train:
+  primitives:
+    zero_primitive_components:
+    - translation_m
+    - orientation_so3
+  bpe:
+    spatial_vocab_size: 1024
+    vocab_size: 16384
+  quality_control:
+    hard_order_1_scale: 3.0
+    min_segment_length: 2

variants/extended-1st-10mm-16k/profiles/eef/primitives.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6d99d92d73fbfe2d96ff317f0eef2d0d2ba6420ac8049c47ae0cc387913854bf
+size 2510

variants/extended-1st-10mm-16k/profiles/eef/processor_config.json

@@ -0,0 +1,3 @@
+{
+  "processor_class": "ActionCodec2Processor"
+}

variants/extended-1st-10mm-16k/profiles/joint/config.json

@@ -0,0 +1,4 @@
+{
+  "model_type": "actioncodec2_unified",
+  "processor_class": "ActionCodec2Processor"
+}

variants/extended-1st-10mm-16k/profiles/joint/config.yaml

@@ -0,0 +1,59 @@
+model_type: actioncodec2_unified
+config_version: 1
+physical:
+  input_dim: 8
+  components:
+    generalized_joint_position:
+      dims:
+        start: 0
+        stop: 7
+      space: additive
+      input_order: 0
+      primitive_order: 1
+      input_transform:
+        scale: 1.0
+        clip: false
+      constraints:
+        order_0:
+          min: -6.283185307179586
+          max: 6.283185307179586
+        order_1:
+          min: -0.35
+          max: 0.35
+      distortion_limit:
+      - 0.008
+      - 0.008
+      - 0.012
+      - 0.015
+      - 0.03
+      - 0.04
+      - 0.04
+      primitive_selection: smooth
+    gripper_open_command:
+      dims:
+      - 7
+      space: additive
+      input_order: 0
+      primitive_order: 0
+      input_transform:
+        scale: 1.0
+        clip: true
+      constraints:
+        order_0:
+          min: 0.0
+          max: 1.0
+      distortion_limit: 0.5
+      primitive_selection: nearest
+set_bpe:
+  lookahead: 8
+  allow_cross_component_merge: false
+train:
+  primitives:
+    zero_primitive_components:
+    - generalized_joint_position
+  bpe:
+    spatial_vocab_size: 1024
+    vocab_size: 16384
+  quality_control:
+    hard_order_1_scale: 3.0
+    min_segment_length: 2

variants/extended-1st-10mm-16k/profiles/joint/primitives.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7424271014df93fbf66a292a1b04aa0f8b999c7c3cf06f965278149d0e41f3e7
+size 2834

variants/extended-1st-10mm-16k/profiles/joint/processor_config.json

@@ -0,0 +1,3 @@
+{
+  "processor_class": "ActionCodec2Processor"
+}

variants/extended-1st-10mm-16k/router_config.yaml

@@ -0,0 +1,346 @@
+model_type: actioncodec2_router
+config_version: 3
+profiles:
+- name: joint
+  token_offset: 0
+  token_budget: 16384
+  artifact_fingerprint: 309e93d0fa330d19b4e597b5b82ef76cce820f536d6f23a31d103e746ab29e86
+- name: eef
+  token_offset: 16384
+  token_budget: 16384
+  artifact_fingerprint: 10eec18e85e63394e59a20ca958f20af761b72575b5b8c9403bc230f4acaba28
+presets:
+- name: single_eef_abs
+  input_dim: 7
+  input: absolute
+  source_hz: 15.0
+  target_hz: 15.0
+  interpolation: cubic
+  components:
+    arm:
+      space: eef
+      position_dims:
+      - 0
+      - 1
+      - 2
+      rotation_dims:
+      - 3
+      - 4
+      - 5
+      rotation_format: rotation_vector
+      gripper_dim: 6
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+- name: single_joint6_abs
+  input_dim: 7
+  input: absolute
+  source_hz: 15.0
+  target_hz: 15.0
+  interpolation: cubic
+  components:
+    arm:
+      space: joint
+      joint_dims:
+      - 0
+      - 1
+      - 2
+      - 3
+      - 4
+      - 5
+      gripper_dim: 6
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+- name: single_joint7_abs
+  input_dim: 8
+  input: absolute
+  source_hz: 15.0
+  target_hz: 15.0
+  interpolation: cubic
+  components:
+    arm:
+      space: joint
+      joint_dims:
+      - 0
+      - 1
+      - 2
+      - 3
+      - 4
+      - 5
+      - 6
+      gripper_dim: 7
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+- name: single_eef_delta
+  input_dim: 7
+  input: delta
+  source_hz: 15.0
+  target_hz: 15.0
+  interpolation: cubic
+  components:
+    arm:
+      space: eef
+      position_dims:
+      - 0
+      - 1
+      - 2
+      rotation_dims:
+      - 3
+      - 4
+      - 5
+      rotation_format: rotation_vector
+      gripper_dim: 6
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+- name: single_joint6_delta
+  input_dim: 7
+  input: delta
+  source_hz: 15.0
+  target_hz: 15.0
+  interpolation: cubic
+  components:
+    arm:
+      space: joint
+      joint_dims:
+      - 0
+      - 1
+      - 2
+      - 3
+      - 4
+      - 5
+      gripper_dim: 6
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+- name: single_joint7_delta
+  input_dim: 8
+  input: delta
+  source_hz: 15.0
+  target_hz: 15.0
+  interpolation: cubic
+  components:
+    arm:
+      space: joint
+      joint_dims:
+      - 0
+      - 1
+      - 2
+      - 3
+      - 4
+      - 5
+      - 6
+      gripper_dim: 7
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+- name: dual_eef_abs
+  input_dim: 14
+  input: absolute
+  source_hz: 15.0
+  target_hz: 15.0
+  interpolation: cubic
+  components:
+    left_arm:
+      space: eef
+      position_dims:
+      - 0
+      - 1
+      - 2
+      rotation_dims:
+      - 3
+      - 4
+      - 5
+      rotation_format: rotation_vector
+      gripper_dim: 6
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+    right_arm:
+      space: eef
+      position_dims:
+      - 7
+      - 8
+      - 9
+      rotation_dims:
+      - 10
+      - 11
+      - 12
+      rotation_format: rotation_vector
+      gripper_dim: 13
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+- name: dual_joint6_abs
+  input_dim: 14
+  input: absolute
+  source_hz: 15.0
+  target_hz: 15.0
+  interpolation: cubic
+  components:
+    left_arm:
+      space: joint
+      joint_dims:
+      - 0
+      - 1
+      - 2
+      - 3
+      - 4
+      - 5
+      gripper_dim: 6
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+    right_arm:
+      space: joint
+      joint_dims:
+      - 7
+      - 8
+      - 9
+      - 10
+      - 11
+      - 12
+      gripper_dim: 13
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+- name: dual_joint7_abs
+  input_dim: 16
+  input: absolute
+  source_hz: 15.0
+  target_hz: 15.0
+  interpolation: cubic
+  components:
+    left_arm:
+      space: joint
+      joint_dims:
+      - 0
+      - 1
+      - 2
+      - 3
+      - 4
+      - 5
+      - 6
+      gripper_dim: 7
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+    right_arm:
+      space: joint
+      joint_dims:
+      - 8
+      - 9
+      - 10
+      - 11
+      - 12
+      - 13
+      - 14
+      gripper_dim: 15
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+- name: dual_eef_delta
+  input_dim: 14
+  input: delta
+  source_hz: 15.0
+  target_hz: 15.0
+  interpolation: cubic
+  components:
+    left_arm:
+      space: eef
+      position_dims:
+      - 0
+      - 1
+      - 2
+      rotation_dims:
+      - 3
+      - 4
+      - 5
+      rotation_format: rotation_vector
+      gripper_dim: 6
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+    right_arm:
+      space: eef
+      position_dims:
+      - 7
+      - 8
+      - 9
+      rotation_dims:
+      - 10
+      - 11
+      - 12
+      rotation_format: rotation_vector
+      gripper_dim: 13
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+- name: dual_joint6_delta
+  input_dim: 14
+  input: delta
+  source_hz: 15.0
+  target_hz: 15.0
+  interpolation: cubic
+  components:
+    left_arm:
+      space: joint
+      joint_dims:
+      - 0
+      - 1
+      - 2
+      - 3
+      - 4
+      - 5
+      gripper_dim: 6
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+    right_arm:
+      space: joint
+      joint_dims:
+      - 7
+      - 8
+      - 9
+      - 10
+      - 11
+      - 12
+      gripper_dim: 13
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+- name: dual_joint7_delta
+  input_dim: 16
+  input: delta
+  source_hz: 15.0
+  target_hz: 15.0
+  interpolation: cubic
+  components:
+    left_arm:
+      space: joint
+      joint_dims:
+      - 0
+      - 1
+      - 2
+      - 3
+      - 4
+      - 5
+      - 6
+      gripper_dim: 7
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+    right_arm:
+      space: joint
+      joint_dims:
+      - 8
+      - 9
+      - 10
+      - 11
+      - 12
+      - 13
+      - 14
+      gripper_dim: 15
+      gripper_threshold: 0.8
+      gripper_open_is_high: true
+- name: single_joint6_abs_continuous_gripper
+  input_dim: 6
+  input: absolute
+  source_hz: 15.0
+  target_hz: 15.0
+  interpolation: cubic
+  components:
+    arm:
+      space: joint
+      joint_dims:
+      - 0
+      - 1
+      - 2
+      - 3
+      - 4
+      - 5

variants/extended-1st-10mm-1k/config.json

@@ -0,0 +1,4 @@
+{
+  "model_type": "actioncodec2",
+  "processor_class": "ActionCodec2"
+}

variants/extended-1st-10mm-1k/processor_config.json

@@ -0,0 +1,11 @@
+{
+  "processor_class": "ActionCodec2",
+  "action_space": "single_eef_delta",
+  "fitted_profiles": [
+    "eef",
+    "joint"
+  ],
+  "auto_map": {
+    "AutoProcessor": "processing_actioncodec2.ActionCodec2"
+  }
+}

variants/extended-1st-10mm-1k/profiles/eef/bpe.json

@@ -0,0 +1,4222 @@
+{
+  "spatial_merges": [
+    [
+      4,
+      13
+    ],
+    [
+      22,
+      84
+    ],
+    [
+      38,
+      61
+    ],
+    [
+      98,
+      99
+    ],
+    [
+      100,
+      101
+    ],
+    [
+      96,
+      102
+    ],
+    [
+      97,
+      102
+    ],
+    [
+      96,
+      100
+    ],
+    [
+      61,
+      96
+    ],
+    [
+      38,
+      96
+    ],
+    [
+      22,
+      98
+    ],
+    [
+      84,
+      98
+    ],
+    [
+      97,
+      100
+    ],
+    [
+      13,
+      99
+    ],
+    [
+      4,
+      99
+    ],
+    [
+      62,
+      107
+    ],
+    [
+      37,
+      106
+    ],
+    [
+      39,
+      106
+    ],
+    [
+      97,
+      101
+    ],
+    [
+      60,
+      107
+    ],
+    [
+      83,
+      108
+    ],
+    [
+      85,
+      108
+    ],
+    [
+      21,
+      109
+    ],
+    [
+      5,
+      111
+    ],
+    [
+      23,
+      109
+    ],
+    [
+      3,
+      111
+    ],
+    [
+      14,
+      112
+    ],
+    [
+      12,
+      112
+    ],
+    [
+      61,
+      97
+    ],
+    [
+      62,
+      96
+    ],
+    [
+      38,
+      60
+    ],
+    [
+      61,
+      116
+    ],
+    [
+      3,
+      13
+    ],
+    [
+      5,
+      13
+    ],
+    [
+      101,
+      113
+    ],
+    [
+      101,
+      117
+    ],
+    [
+      60,
+      96
+    ],
+    [
+      22,
+      83
+    ],
+    [
+      101,
+      114
+    ],
+    [
+      22,
+      85
+    ],
+    [
+      101,
+      115
+    ],
+    [
+      23,
+      84
+    ],
+    [
+      4,
+      14
+    ],
+    [
+      4,
+      12
+    ],
+    [
+      21,
+      84
+    ],
+    [
+      38,
+      62
+    ],
+    [
+      105,
+      120
+    ],
+    [
+      105,
+      122
+    ],
+    [
+      105,
+      118
+    ],
+    [
+      105,
+      119
+    ],
+    [
+      105,
+      121
+    ],
+    [
+      105,
+      123
+    ],
+    [
+      105,
+      125
+    ],
+    [
+      105,
+      124
+    ],
+    [
+      116,
+      128
+    ],
+    [
+      37,
+      126
+    ],
+    [
+      97,
+      128
+    ],
+    [
+      39,
+      126
+    ],
+    [
+      37,
+      129
+    ],
+    [
+      37,
+      127
+    ],
+    [
+      39,
+      129
+    ],
+    [
+      39,
+      127
+    ],
+    [
+      23,
+      98
+    ],
+    [
+      21,
+      98
+    ],
+    [
+      39,
+      134
+    ],
+    [
+      110,
+      120
+    ],
+    [
+      37,
+      134
+    ],
+    [
+      110,
+      119
+    ],
+    [
+      110,
+      118
+    ],
+    [
+      97,
+      143
+    ],
+    [
+      116,
+      143
+    ],
+    [
+      3,
+      99
+    ],
+    [
+      110,
+      121
+    ],
+    [
+      5,
+      99
+    ],
+    [
+      110,
+      125
+    ],
+    [
+      110,
+      124
+    ],
+    [
+      60,
+      97
+    ],
+    [
+      105,
+      130
+    ],
+    [
+      113,
+      122
+    ],
+    [
+      115,
+      124
+    ],
+    [
+      105,
+      131
+    ],
+    [
+      114,
+      125
+    ],
+    [
+      110,
+      122
+    ],
+    [
+      110,
+      123
+    ],
+    [
+      105,
+      140
+    ],
+    [
+      83,
+      160
+    ],
+    [
+      135,
+      141
+    ],
+    [
+      62,
+      97
+    ],
+    [
+      85,
+      160
+    ],
+    [
+      85,
+      161
+    ],
+    [
+      83,
+      161
+    ],
+    [
+      117,
+      120
+    ],
+    [
+      23,
+      85
+    ],
+    [
+      14,
+      169
+    ],
+    [
+      12,
+      171
+    ],
+    [
+      12,
+      169
+    ],
+    [
+      23,
+      83
+    ],
+    [
+      137,
+      141
+    ],
+    [
+      14,
+      171
+    ],
+    [
+      137,
+      140
+    ],
+    [
+      21,
+      85
+    ],
+    [
+      3,
+      12
+    ],
+    [
+      3,
+      14
+    ],
+    [
+      139,
+      141
+    ],
+    [
+      21,
+      83
+    ],
+    [
+      130,
+      139
+    ],
+    [
+      131,
+      142
+    ],
+    [
+      5,
+      12
+    ],
+    [
+      130,
+      142
+    ],
+    [
+      131,
+      139
+    ],
+    [
+      141,
+      142
+    ],
+    [
+      131,
+      135
+    ],
+    [
+      5,
+      14
+    ],
+    [
+      131,
+      137
+    ],
+    [
+      130,
+      137
+    ],
+    [
+      135,
+      140
+    ],
+    [
+      101,
+      159
+    ],
+    [
+      101,
+      157
+    ],
+    [
+      37,
+      174
+    ],
+    [
+      114,
+      118
+    ],
+    [
+      130,
+      135
+    ],
+    [
+      115,
+      119
+    ],
+    [
+      113,
+      123
+    ],
+    [
+      39,
+      174
+    ],
+    [
+      117,
+      121
+    ],
+    [
+      113,
+      118
+    ],
+    [
+      101,
+      162
+    ],
+    [
+      60,
+      116
+    ],
+    [
+      101,
+      164
+    ],
+    [
+      139,
+      140
+    ],
+    [
+      113,
+      119
+    ],
+    [
+      140,
+      142
+    ],
+    [
+      117,
+      119
+    ],
+    [
+      115,
+      123
+    ],
+    [
+      39,
+      185
+    ],
+    [
+      114,
+      121
+    ],
+    [
+      40,
+      106
+    ],
+    [
+      117,
+      118
+    ],
+    [
+      113,
+      121
+    ],
+    [
+      37,
+      185
+    ],
+    [
+      62,
+      116
+    ],
+    [
+      36,
+      106
+    ],
+    [
+      117,
+      123
+    ],
+    [
+      114,
+      123
+    ],
+    [
+      125,
+      153
+    ],
+    [
+      115,
+      118
+    ],
+    [
+      114,
+      119
+    ],
+    [
+      120,
+      154
+    ],
+    [
+      124,
+      155
+    ],
+    [
+      63,
+      107
+    ],
+    [
+      139,
+      175
+    ],
+    [
+      115,
+      121
+    ],
+    [
+      142,
+      178
+    ],
+    [
+      59,
+      107
+    ],
+    [
+      114,
+      122
+    ],
+    [
+      63,
+      96
+    ],
+    [
+      115,
+      122
+    ],
+    [
+      115,
+      120
+    ],
+    [
+      59,
+      96
+    ],
+    [
+      105,
+      183
+    ],
+    [
+      114,
+      120
+    ],
+    [
+      119,
+      155
+    ],
+    [
+      118,
+      153
+    ],
+    [
+      105,
+      186
+    ],
+    [
+      105,
+      187
+    ],
+    [
+      105,
+      188
+    ],
+    [
+      113,
+      124
+    ],
+    [
+      122,
+      167
+    ],
+    [
+      105,
+      184
+    ],
+    [
+      113,
+      125
+    ],
+    [
+      119,
+      154
+    ],
+    [
+      137,
+      182
+    ],
+    [
+      37,
+      225
+    ],
+    [
+      39,
+      225
+    ],
+    [
+      118,
+      154
+    ],
+    [
+      139,
+      178
+    ],
+    [
+      117,
+      125
+    ],
+    [
+      113,
+      203
+    ],
+    [
+      135,
+      178
+    ],
+    [
+      117,
+      124
+    ],
+    [
+      142,
+      175
+    ],
+    [
+      135,
+      182
+    ],
+    [
+      105,
+      193
+    ],
+    [
+      137,
+      175
+    ],
+    [
+      137,
+      178
+    ],
+    [
+      39,
+      238
+    ],
+    [
+      105,
+      191
+    ],
+    [
+      135,
+      175
+    ],
+    [
+      105,
+      196
+    ],
+    [
+      118,
+      167
+    ],
+    [
+      105,
+      195
+    ],
+    [
+      105,
+      201
+    ],
+    [
+      82,
+      108
+    ],
+    [
+      105,
+      192
+    ],
+    [
+      119,
+      167
+    ],
+    [
+      37,
+      238
+    ],
+    [
+      86,
+      108
+    ],
+    [
+      139,
+      182
+    ],
+    [
+      113,
+      183
+    ],
+    [
+      119,
+      153
+    ],
+    [
+      118,
+      155
+    ],
+    [
+      121,
+      154
+    ],
+    [
+      142,
+      182
+    ],
+    [
+      121,
+      153
+    ],
+    [
+      113,
+      186
+    ],
+    [
+      114,
+      184
+    ],
+    [
+      115,
+      197
+    ],
+    [
+      124,
+      159
+    ],
+    [
+      117,
+      122
+    ],
+    [
+      122,
+      157
+    ],
+    [
+      115,
+      191
+    ],
+    [
+      105,
+      208
+    ],
+    [
+      59,
+      97
+    ],
+    [
+      125,
+      157
+    ],
+    [
+      139,
+      199
+    ],
+    [
+      40,
+      127
+    ],
+    [
+      36,
+      127
+    ],
+    [
+      122,
+      159
+    ],
+    [
+      22,
+      82
+    ],
+    [
+      141,
+      194
+    ],
+    [
+      120,
+      155
+    ],
+    [
+      110,
+      187
+    ],
+    [
+      114,
+      193
+    ],
+    [
+      120,
+      153
+    ],
+    [
+      110,
+      188
+    ],
+    [
+      22,
+      86
+    ],
+    [
+      110,
+      204
+    ],
+    [
+      114,
+      192
+    ],
+    [
+      110,
+      184
+    ],
+    [
+      121,
+      155
+    ],
+    [
+      40,
+      134
+    ],
+    [
+      123,
+      155
+    ],
+    [
+      110,
+      197
+    ],
+    [
+      124,
+      162
+    ],
+    [
+      141,
+      202
+    ],
+    [
+      117,
+      204
+    ],
+    [
+      115,
+      213
+    ],
+    [
+      115,
+      196
+    ],
+    [
+      130,
+      198
+    ],
+    [
+      139,
+      200
+    ],
+    [
+      125,
+      164
+    ],
+    [
+      37,
+      253
+    ],
+    [
+      137,
+      200
+    ],
+    [
+      135,
+      205
+    ],
+    [
+      131,
+      194
+    ],
+    [
+      137,
+      199
+    ],
+    [
+      113,
+      120
+    ],
+    [
+      4,
+      15
+    ],
+    [
+      121,
+      167
+    ],
+    [
+      114,
+      195
+    ],
+    [
+      117,
+      206
+    ],
+    [
+      37,
+      256
+    ],
+    [
+      135,
+      199
+    ],
+    [
+      120,
+      162
+    ],
+    [
+      140,
+      198
+    ],
+    [
+      123,
+      167
+    ],
+    [
+      113,
+      190
+    ],
+    [
+      117,
+      187
+    ],
+    [
+      130,
+      202
+    ],
+    [
+      135,
+      210
+    ],
+    [
+      113,
+      207
+    ],
+    [
+      117,
+      188
+    ],
+    [
+      137,
+      210
+    ],
+    [
+      36,
+      126
+    ],
+    [
+      36,
+      134
+    ],
+    [
+      110,
+      209
+    ],
+    [
+      142,
+      205
+    ],
+    [
+      135,
+      200
+    ],
+    [
+      40,
+      126
+    ],
+    [
+      39,
+      253
+    ],
+    [
+      110,
+      211
+    ],
+    [
+      114,
+      201
+    ],
+    [
+      142,
+      200
+    ],
+    [
+      124,
+      154
+    ],
+    [
+      125,
+      154
+    ],
+    [
+      120,
+      164
+    ],
+    [
+      139,
+      205
+    ],
+    [
+      118,
+      157
+    ],
+    [
+      123,
+      154
+    ],
+    [
+      115,
+      227
+    ],
+    [
+      123,
+      153
+    ],
+    [
+      119,
+      159
+    ],
+    [
+      2,
+      13
+    ],
+    [
+      130,
+      194
+    ],
+    [
+      39,
+      256
+    ],
+    [
+      137,
+      205
+    ],
+    [
+      142,
+      210
+    ],
+    [
+      131,
+      202
+    ],
+    [
+      119,
+      162
+    ],
+    [
+      140,
+      190
+    ],
+    [
+      6,
+      13
+    ],
+    [
+      122,
+      153
+    ],
+    [
+      131,
+      198
+    ],
+    [
+      4,
+      11
+    ],
+    [
+      122,
+      155
+    ],
+    [
+      118,
+      164
+    ],
+    [
+      63,
+      97
+    ],
+    [
+      131,
+      190
+    ],
+    [
+      123,
+      157
+    ],
+    [
+      110,
+      183
+    ],
+    [
+      110,
+      208
+    ],
+    [
+      123,
+      159
+    ],
+    [
+      110,
+      192
+    ],
+    [
+      141,
+      190
+    ],
+    [
+      123,
+      162
+    ],
+    [
+      142,
+      199
+    ],
+    [
+      24,
+      84
+    ],
+    [
+      121,
+      157
+    ],
+    [
+      115,
+      229
+    ],
+    [
+      110,
+      229
+    ],
+    [
+      110,
+      186
+    ],
+    [
+      121,
+      164
+    ],
+    [
+      125,
+      167
+    ],
+    [
+      113,
+      201
+    ],
+    [
+      140,
+      194
+    ],
+    [
+      124,
+      167
+    ],
+    [
+      118,
+      159
+    ],
+    [
+      139,
+      210
+    ],
+    [
+      110,
+      196
+    ],
+    [
+      113,
+      227
+    ],
+    [
+      110,
+      218
+    ],
+    [
+      15,
+      112
+    ],
+    [
+      110,
+      195
+    ],
+    [
+      123,
+      164
+    ],
+    [
+      110,
+      206
+    ],
+    [
+      110,
+      212
+    ],
+    [
+      119,
+      157
+    ],
+    [
+      110,
+      213
+    ],
+    [
+      141,
+      198
+    ],
+    [
+      11,
+      112
+    ],
+    [
+      130,
+      190
+    ],
+    [
+      119,
+      164
+    ],
+    [
+      121,
+      159
+    ],
+    [
+      118,
+      162
+    ],
+    [
+      121,
+      162
+    ],
+    [
+      110,
+      203
+    ],
+    [
+      114,
+      208
+    ],
+    [
+      155,
+      197
+    ],
+    [
+      110,
+      193
+    ],
+    [
+      153,
+      184
+    ],
+    [
+      2,
+      12
+    ],
+    [
+      20,
+      84
+    ],
+    [
+      140,
+      202
+    ],
+    [
+      110,
+      207
+    ],
+    [
+      157,
+      201
+    ],
+    [
+      110,
+      191
+    ],
+    [
+      120,
+      167
+    ],
+    [
+      159,
+      227
+    ],
+    [
+      117,
+      207
+    ],
+    [
+      38,
+      310
+    ],
+    [
+      124,
+      234
+    ],
+    [
+      24,
+      85
+    ],
+    [
+      114,
+      209
+    ],
+    [
+      114,
+      124
+    ],
+    [
+      114,
+      183
+    ],
+    [
+      113,
+      212
+    ],
+    [
+      117,
+      212
+    ],
+    [
+      115,
+      212
+    ],
+    [
+      115,
+      125
+    ],
+    [
+      110,
+      201
+    ],
+    [
+      125,
+      239
+    ],
+    [
+      2,
+      111
+    ],
+    [
+      110,
+      227
+    ],
+    [
+      113,
+      218
+    ],
+    [
+      115,
+      186
+    ],
+    [
+      113,
+      209
+    ],
+    [
+      119,
+      221
+    ],
+    [
+      114,
+      218
+    ],
+    [
+      122,
+      154
+    ],
+    [
+      117,
+      229
+    ],
+    [
+      117,
+      211
+    ],
+    [
+      115,
+      211
+    ],
+    [
+      117,
+      209
+    ],
+    [
+      117,
+      208
+    ],
+    [
+      6,
+      111
+    ],
+    [
+      115,
+      187
+    ],
+    [
+      114,
+      207
+    ],
+    [
+      117,
+      218
+    ],
+    [
+      114,
+      188
+    ],
+    [
+      101,
+      234
+    ],
+    [
+      125,
+      216
+    ],
+    [
+      154,
+      187
+    ],
+    [
+      101,
+      239
+    ],
+    [
+      118,
+      216
+    ],
+    [
+      114,
+      203
+    ],
+    [
+      113,
+      211
+    ],
+    [
+      23,
+      86
+    ],
+    [
+      115,
+      203
+    ],
+    [
+      118,
+      237
+    ],
+    [
+      120,
+      221
+    ],
+    [
+      120,
+      216
+    ],
+    [
+      24,
+      83
+    ],
+    [
+      124,
+      221
+    ],
+    [
+      36,
+      174
+    ],
+    [
+      154,
+      188
+    ],
+    [
+      119,
+      232
+    ],
+    [
+      115,
+      206
+    ],
+    [
+      115,
+      204
+    ],
+    [
+      20,
+      85
+    ],
+    [
+      162,
+      229
+    ],
+    [
+      157,
+      183
+    ],
+    [
+      114,
+      204
+    ],
+    [
+      86,
+      160
+    ],
+    [
+      153,
+      192
+    ],
+    [
+      124,
+      232
+    ],
+    [
+      24,
+      109
+    ],
+    [
+      38,
+      394
+    ],
+    [
+      159,
+      186
+    ],
+    [
+      115,
+      218
+    ],
+    [
+      40,
+      174
+    ],
+    [
+      122,
+      247
+    ],
+    [
+      114,
+      211
+    ],
+    [
+      113,
+      193
+    ],
+    [
+      113,
+      213
+    ]
+  ],
+  "temporal_merges": [
+    [
+      103,
+      103,
+      2
+    ],
+    [
+      104,
+      104,
+      1
+    ],
+    [
+      512,
+      512,
+      4
+    ],
+    [
+      513,
+      513,
+      2
+    ],
+    [
+      514,
+      514,
+      1
+    ],
+    [
+      512,
+      103,
+      4
+    ],
+    [
+      515,
+      515,
+      4
+    ],
+    [
+      103,
+      103,
+      4
+    ],
+    [
+      513,
+      104,
+      2
+    ],
+    [
+      104,
+      104,
+      2
+    ],
+    [
+      103,
+      512,
+      4
+    ],
+    [
+      103,
+      103,
+      6
+    ],
+    [
+      512,
+      103,
+      6
+    ],
+    [
+      515,
+      104,
+      4
+    ],
+    [
+      513,
+      104,
+      3
+    ],
+    [
+      515,
+      513,
+      4
+    ],
+    [
+      104,
+      104,
+      3
+    ],
+    [
+      103,
+      133,
+      2
+    ],
+    [
+      103,
+      132,
+      2
+    ],
+    [
+      103,
+      136,
+      2
+    ],
+    [
+      515,
+      520,
+      4
+    ],
+    [
+      103,
+      138,
+      2
+    ],
+    [
+      103,
+      144,
+      2
+    ],
+    [
+      104,
+      513,
+      2
+    ],
+    [
+      512,
+      132,
+      4
+    ],
+    [
+      512,
+      133,
+      4
+    ],
+    [
+      103,
+      145,
+      2
+    ],
+    [
+      103,
+      146,
+      2
+    ],
+    [
+      103,
+      147,
+      2
+    ],
+    [
+      514,
+      517,
+      1
+    ],
+    [
+      103,
+      148,
+      2
+    ],
+    [
+      512,
+      136,
+      4
+    ],
+    [
+      138,
+      138,
+      3
+    ],
+    [
+      512,
+      144,
+      4
+    ],
+    [
+      103,
+      149,
+      2
+    ],
+    [
+      514,
+      517,
+      3
+    ],
+    [
+      512,
+      145,
+      4
+    ],
+    [
+      150,
+      136,
+      1
+    ],
+    [
+      132,
+      132,
+      2
+    ],
+    [
+      512,
+      138,
+      4
+    ],
+    [
+      512,
+      147,
+      4
+    ],
+    [
+      512,
+      146,
+      4
+    ],
+    [
+      103,
+      151,
+      2
+    ],
+    [
+      133,
+      133,
+      3
+    ],
+    [
+      517,
+      514,
+      1
+    ],
+    [
+      103,
+      150,
+      2
+    ],
+    [
+      136,
+      136,
+      3
+    ],
+    [
+      512,
+      149,
+      4
+    ],
+    [
+      513,
+      513,
+      3
+    ],
+    [
+      512,
+      148,
+      4
+    ],
+    [
+      520,
+      104,
+      4
+    ],
+    [
+      145,
+      132,
+      1
+    ],
+    [
+      151,
+      138,
+      1
+    ],
+    [
+      104,
+      152,
+      1
+    ],
+    [
+      144,
+      133,
+      1
+    ],
+    [
+      132,
+      145,
+      1
+    ],
+    [
+      512,
+      150,
+      4
+    ],
+    [
+      104,
+      156,
+      1
+    ],
+    [
+      512,
+      151,
+      4
+    ],
+    [
+      146,
+      146,
+      2
+    ],
+    [
+      104,
+      158,
+      1
+    ],
+    [
+      147,
+      147,
+      2
+    ],
+    [
+      163,
+      152,
+      1
+    ],
+    [
+      517,
+      132,
+      6
+    ],
+    [
+      149,
+      149,
+      4
+    ],
+    [
+      136,
+      136,
+      4
+    ],
+    [
+      517,
+      133,
+      6
+    ],
+    [
+      138,
+      138,
+      4
+    ],
+    [
+      144,
+      133,
+      2
+    ],
+    [
+      172,
+      156,
+      1
+    ],
+    [
+      148,
+      148,
+      4
+    ],
+    [
+      513,
+      152,
+      2
+    ],
+    [
+      104,
+      165,
+      1
+    ],
+    [
+      104,
+      166,
+      1
+    ],
+    [
+      519,
+      144,
+      2
+    ],
+    [
+      173,
+      158,
+      1
+    ],
+    [
+      517,
+      147,
+      6
+    ],
+    [
+      517,
+      136,
+      6
+    ],
+    [
+      517,
+      138,
+      6
+    ],
+    [
+      517,
+      146,
+      6
+    ],
+    [
+      513,
+      156,
+      2
+    ],
+    [
+      104,
+      163,
+      1
+    ],
+    [
+      104,
+      168,
+      1
+    ],
+    [
+      103,
+      103,
+      1
+    ],
+    [
+      519,
+      132,
+      2
+    ],
+    [
+      517,
+      145,
+      6
+    ],
+    [
+      177,
+      177,
+      2
+    ],
+    [
+      133,
+      133,
+      2
+    ],
+    [
+      104,
+      170,
+      1
+    ],
+    [
+      513,
+      158,
+      2
+    ],
+    [
+      517,
+      144,
+      6
+    ],
+    [
+      519,
+      133,
+      2
+    ],
+    [
+      179,
+      179,
+      2
+    ],
+    [
+      145,
+      132,
+      2
+    ],
+    [
+      149,
+      149,
+      5
+    ],
+    [
+      513,
+      168,
+      2
+    ],
+    [
+      520,
+      152,
+      3
+    ],
+    [
+      515,
+      521,
+      4
+    ],
+    [
+      132,
+      132,
+      3
+    ],
+    [
+      517,
+      148,
+      6
+    ],
+    [
+      519,
+      146,
+      2
+    ],
+    [
+      519,
+      147,
+      2
+    ],
+    [
+      138,
+      151,
+      1
+    ],
+    [
+      136,
+      150,
+      1
+    ],
+    [
+      513,
+      163,
+      2
+    ],
+    [
+      520,
+      156,
+      3
+    ],
+    [
+      519,
+      145,
+      2
+    ],
+    [
+      517,
+      149,
+      6
+    ],
+    [
+      176,
+      176,
+      2
+    ],
+    [
+      513,
+      170,
+      2
+    ],
+    [
+      520,
+      158,
+      3
+    ],
+    [
+      133,
+      144,
+      1
+    ],
+    [
+      148,
+      148,
+      5
+    ],
+    [
+      152,
+      163,
+      1
+    ],
+    [
+      513,
+      165,
+      2
+    ],
+    [
+      180,
+      168,
+      1
+    ],
+    [
+      133,
+      144,
+      2
+    ],
+    [
+      513,
+      166,
+      2
+    ],
+    [
+      156,
+      156,
+      3
+    ],
+    [
+      520,
+      168,
+      3
+    ],
+    [
+      136,
+      136,
+      2
+    ],
+    [
+      520,
+      163,
+      3
+    ],
+    [
+      158,
+      158,
+      3
+    ],
+    [
+      138,
+      138,
+      2
+    ],
+    [
+      132,
+      145,
+      2
+    ],
+    [
+      157,
+      157,
+      2
+    ],
+    [
+      519,
+      136,
+      2
+    ],
+    [
+      519,
+      138,
+      2
+    ],
+    [
+      150,
+      136,
+      2
+    ],
+    [
+      166,
+      166,
+      2
+    ],
+    [
+      519,
+      148,
+      2
+    ],
+    [
+      520,
+      170,
+      3
+    ],
+    [
+      145,
+      145,
+      2
+    ],
+    [
+      165,
+      165,
+      2
+    ],
+    [
+      104,
+      172,
+      1
+    ],
+    [
+      146,
+      146,
+      3
+    ],
+    [
+      514,
+      144,
+      1
+    ],
+    [
+      164,
+      164,
+      2
+    ],
+    [
+      147,
+      147,
+      3
+    ],
+    [
+      151,
+      138,
+      2
+    ],
+    [
+      104,
+      173,
+      1
+    ],
+    [
+      132,
+      103,
+      2
+    ],
+    [
+      104,
+      181,
+      1
+    ],
+    [
+      519,
+      149,
+      2
+    ],
+    [
+      519,
+      151,
+      2
+    ],
+    [
+      517,
+      150,
+      6
+    ],
+    [
+      519,
+      150,
+      2
+    ],
+    [
+      521,
+      152,
+      1
+    ],
+    [
+      517,
+      151,
+      6
+    ],
+    [
+      144,
+      103,
+      2
+    ],
+    [
+      520,
+      165,
+      3
+    ],
+    [
+      133,
+      103,
+      2
+    ],
+    [
+      146,
+      103,
+      2
+    ],
+    [
+      136,
+      103,
+      2
+    ],
+    [
+      162,
+      162,
+      2
+    ],
+    [
+      147,
+      103,
+      2
+    ],
+    [
+      520,
+      166,
+      3
+    ],
+    [
+      138,
+      103,
+      2
+    ],
+    [
+      515,
+      156,
+      4
+    ],
+    [
+      149,
+      103,
+      2
+    ],
+    [
+      145,
+      103,
+      2
+    ],
+    [
+      148,
+      103,
+      2
+    ],
+    [
+      514,
+      144,
+      3
+    ],
+    [
+      104,
+      180,
+      1
+    ],
+    [
+      515,
+      152,
+      4
+    ],
+    [
+      117,
+      117,
+      2
+    ],
+    [
+      521,
+      152,
+      3
+    ],
+    [
+      159,
+      159,
+      2
+    ],
+    [
+      136,
+      150,
+      2
+    ],
+    [
+      513,
+      172,
+      2
+    ],
+    [
+      515,
+      158,
+      4
+    ],
+    [
+      114,
+      114,
+      2
+    ],
+    [
+      113,
+      113,
+      2
+    ],
+    [
+      514,
+      133,
+      1
+    ],
+    [
+      115,
+      115,
+      2
+    ],
+    [
+      513,
+      173,
+      2
+    ],
+    [
+      515,
+      163,
+      4
+    ],
+    [
+      138,
+      151,
+      2
+    ],
+    [
+      514,
+      512,
+      5
+    ],
+    [
+      155,
+      155,
+      2
+    ],
+    [
+      513,
+      181,
+      2
+    ],
+    [
+      156,
+      172,
+      1
+    ],
+    [
+      144,
+      144,
+      3
+    ],
+    [
+      151,
+      151,
+      3
+    ],
+    [
+      177,
+      177,
+      3
+    ],
+    [
+      158,
+      158,
+      4
+    ],
+    [
+      152,
+      152,
+      3
+    ],
+    [
+      132,
+      132,
+      4
+    ],
+    [
+      515,
+      170,
+      4
+    ],
+    [
+      179,
+      179,
+      3
+    ],
+    [
+      251,
+      251,
+      2
+    ],
+    [
+      520,
+      172,
+      3
+    ],
+    [
+      521,
+      156,
+      3
+    ],
+    [
+      515,
+      526,
+      4
+    ],
+    [
+      514,
+      144,
+      5
+    ],
+    [
+      513,
+      180,
+      2
+    ],
+    [
+      515,
+      168,
+      4
+    ],
+    [
+      520,
+      173,
+      3
+    ],
+    [
+      149,
+      149,
+      3
+    ],
+    [
+      514,
+      133,
+      3
+    ],
+    [
+      150,
+      103,
+      2
+    ],
+    [
+      168,
+      168,
+      3
+    ],
+    [
+      153,
+      153,
+      2
+    ],
+    [
+      520,
+      181,
+      3
+    ],
+    [
+      247,
+      247,
+      2
+    ],
+    [
+      148,
+      148,
+      3
+    ],
+    [
+      520,
+      180,
+      3
+    ],
+    [
+      521,
+      170,
+      3
+    ],
+    [
+      176,
+      176,
+      3
+    ],
+    [
+      158,
+      173,
+      1
+    ],
+    [
+      515,
+      165,
+      4
+    ],
+    [
+      146,
+      146,
+      4
+    ],
+    [
+      521,
+      168,
+      3
+    ],
+    [
+      133,
+      133,
+      4
+    ],
+    [
+      166,
+      166,
+      3
+    ],
+    [
+      154,
+      154,
+      2
+    ],
+    [
+      151,
+      103,
+      2
+    ],
+    [
+      165,
+      165,
+      3
+    ],
+    [
+      514,
+      132,
+      1
+    ],
+    [
+      515,
+      166,
+      4
+    ],
+    [
+      147,
+      147,
+      4
+    ],
+    [
+      521,
+      163,
+      3
+    ],
+    [
+      145,
+      145,
+      3
+    ],
+    [
+      150,
+      150,
+      3
+    ],
+    [
+      514,
+      133,
+      5
+    ],
+    [
+      512,
+      512,
+      1
+    ],
+    [
+      189,
+      189,
+      2
+    ],
+    [
+      512,
+      103,
+      1
+    ],
+    [
+      152,
+      163,
+      2
+    ],
+    [
+      521,
+      158,
+      3
+    ],
+    [
+      156,
+      156,
+      4
+    ],
+    [
+      105,
+      105,
+      2
+    ],
+    [
+      167,
+      167,
+      2
+    ],
+    [
+      234,
+      234,
+      2
+    ],
+    [
+      514,
+      512,
+      3
+    ],
+    [
+      522,
+      132,
+      2
+    ],
+    [
+      144,
+      144,
+      4
+    ],
+    [
+      216,
+      216,
+      2
+    ],
+    [
+      515,
+      172,
+      4
+    ],
+    [
+      517,
+      517,
+      1
+    ],
+    [
+      522,
+      136,
+      2
+    ],
+    [
+      170,
+      170,
+      5
+    ],
+    [
+      110,
+      110,
+      2
+    ],
+    [
+      515,
+      173,
+      4
+    ],
+    [
+      522,
+      147,
+      2
+    ],
+    [
+      103,
+      176,
+      2
+    ],
+    [
+      522,
+      146,
+      2
+    ],
+    [
+      522,
+      133,
+      2
+    ],
+    [
+      522,
+      138,
+      2
+    ],
+    [
+      514,
+      145,
+      5
+    ],
+    [
+      515,
+      180,
+      4
+    ],
+    [
+      239,
+      239,
+      2
+    ],
+    [
+      521,
+      165,
+      3
+    ],
+    [
+      514,
+      148,
+      1
+    ],
+    [
+      521,
+      166,
+      3
+    ],
+    [
+      163,
+      152,
+      2
+    ],
+    [
+      136,
+      136,
+      5
+    ],
+    [
+      168,
+      180,
+      1
+    ],
+    [
+      522,
+      144,
+      2
+    ],
+    [
+      517,
+      512,
+      1
+    ],
+    [
+      515,
+      181,
+      4
+    ],
+    [
+      132,
+      132,
+      5
+    ],
+    [
+      514,
+      149,
+      1
+    ],
+    [
+      151,
+      151,
+      4
+    ],
+    [
+      514,
+      146,
+      1
+    ],
+    [
+      514,
+      147,
+      1
+    ],
+    [
+      514,
+      136,
+      1
+    ],
+    [
+      156,
+      172,
+      2
+    ],
+    [
+      237,
+      237,
+      2
+    ],
+    [
+      138,
+      138,
+      5
+    ],
+    [
+      149,
+      149,
+      2
+    ],
+    [
+      514,
+      138,
+      1
+    ],
+    [
+      152,
+      152,
+      2
+    ],
+    [
+      158,
+      165,
+      1
+    ],
+    [
+      512,
+      176,
+      4
+    ],
+    [
+      514,
+      132,
+      5
+    ],
+    [
+      148,
+      148,
+      6
+    ],
+    [
+      104,
+      104,
+      4
+    ],
+    [
+      156,
+      166,
+      1
+    ],
+    [
+      514,
+      149,
+      5
+    ],
+    [
+      103,
+      189,
+      2
+    ],
+    [
+      150,
+      150,
+      4
+    ],
+    [
+      146,
+      146,
+      5
+    ],
+    [
+      525,
+      152,
+      5
+    ],
+    [
+      165,
+      158,
+      1
+    ],
+    [
+      177,
+      177,
+      4
+    ],
+    [
+      170,
+      170,
+      6
+    ],
+    [
+      147,
+      147,
+      5
+    ],
+    [
+      514,
+      148,
+      5
+    ],
+    [
+      522,
+      145,
+      2
+    ],
+    [
+      179,
+      136,
+      2
+    ],
+    [
+      525,
+      156,
+      5
+    ],
+    [
+      521,
+      173,
+      3
+    ],
+    [
+      166,
+      156,
+      1
+    ],
+    [
+      133,
+      133,
+      5
+    ],
+    [
+      221,
+      221,
+      2
+    ],
+    [
+      158,
+      168,
+      1
+    ],
+    [
+      148,
+      148,
+      2
+    ],
+    [
+      232,
+      232,
+      2
+    ],
+    [
+      514,
+      138,
+      5
+    ],
+    [
+      145,
+      145,
+      4
+    ],
+    [
+      117,
+      117,
+      3
+    ],
+    [
+      514,
+      136,
+      5
+    ],
+    [
+      525,
+      163,
+      5
+    ],
+    [
+      222,
+      222,
+      2
+    ],
+    [
+      521,
+      181,
+      3
+    ],
+    [
+      514,
+      512,
+      1
+    ],
+    [
+      152,
+      104,
+      1
+    ],
+    [
+      166,
+      168,
+      1
+    ],
+    [
+      165,
+      168,
+      1
+    ],
+    [
+      514,
+      147,
+      5
+    ],
+    [
+      104,
+      152,
+      2
+    ],
+    [
+      514,
+      146,
+      5
+    ],
+    [
+      149,
+      149,
+      6
+    ],
+    [
+      514,
+      151,
+      1
+    ],
+    [
+      521,
+      180,
+      3
+    ],
+    [
+      144,
+      144,
+      2
+    ],
+    [
+      525,
+      158,
+      5
+    ],
+    [
+      172,
+      156,
+      2
+    ],
+    [
+      514,
+      145,
+      1
+    ],
+    [
+      522,
+      148,
+      2
+    ],
+    [
+      514,
+      150,
+      1
+    ],
+    [
+      113,
+      113,
+      3
+    ],
+    [
+      103,
+      179,
+      2
+    ],
+    [
+      163,
+      104,
+      1
+    ],
+    [
+      114,
+      114,
+      3
+    ],
+    [
+      115,
+      115,
+      3
+    ],
+    [
+      157,
+      157,
+      3
+    ],
+    [
+      165,
+      152,
+      1
+    ],
+    [
+      155,
+      155,
+      3
+    ],
+    [
+      166,
+      152,
+      1
+    ],
+    [
+      144,
+      512,
+      2
+    ],
+    [
+      220,
+      220,
+      2
+    ],
+    [
+      290,
+      290,
+      2
+    ],
+    [
+      177,
+      138,
+      2
+    ],
+    [
+      156,
+      168,
+      1
+    ],
+    [
+      132,
+      512,
+      2
+    ],
+    [
+      133,
+      512,
+      2
+    ],
+    [
+      164,
+      164,
+      3
+    ],
+    [
+      525,
+      168,
+      5
+    ],
+    [
+      514,
+      150,
+      5
+    ],
+    [
+      525,
+      170,
+      5
+    ],
+    [
+      158,
+      152,
+      1
+    ],
+    [
+      514,
+      151,
+      5
+    ],
+    [
+      132,
+      176,
+      2
+    ],
+    [
+      521,
+      172,
+      3
+    ],
+    [
+      294,
+      294,
+      2
+    ],
+    [
+      147,
+      512,
+      2
+    ],
+    [
+      148,
+      144,
+      2
+    ],
+    [
+      522,
+      149,
+      2
+    ],
+    [
+      103,
+      136,
+      4
+    ],
+    [
+      173,
+      158,
+      2
+    ],
+    [
+      146,
+      512,
+      2
+    ],
+    [
+      165,
+      104,
+      1
+    ],
+    [
+      103,
+      132,
+      4
+    ],
+    [
+      103,
+      138,
+      4
+    ],
+    [
+      130,
+      130,
+      2
+    ],
+    [
+      144,
+      148,
+      2
+    ],
+    [
+      166,
+      104,
+      1
+    ],
+    [
+      156,
+      152,
+      1
+    ],
+    [
+      179,
+      179,
+      4
+    ],
+    [
+      519,
+      132,
+      6
+    ],
+    [
+      145,
+      145,
+      5
+    ],
+    [
+      189,
+      189,
+      3
+    ],
+    [
+      527,
+      152,
+      6
+    ],
+    [
+      153,
+      153,
+      3
+    ],
+    [
+      524,
+      132,
+      4
+    ],
+    [
+      519,
+      148,
+      6
+    ],
+    [
+      522,
+      151,
+      2
+    ],
+    [
+      522,
+      150,
+      2
+    ],
+    [
+      159,
+      159,
+      3
+    ],
+    [
+      514,
+      103,
+      5
+    ],
+    [
+      163,
+      170,
+      1
+    ],
+    [
+      519,
+      144,
+      6
+    ],
+    [
+      138,
+      512,
+      2
+    ],
+    [
+      162,
+      162,
+      3
+    ],
+    [
+      519,
+      136,
+      6
+    ],
+    [
+      156,
+      104,
+      1
+    ],
+    [
+      181,
+      181,
+      3
+    ],
+    [
+      103,
+      177,
+      2
+    ],
+    [
+      158,
+      104,
+      1
+    ],
+    [
+      151,
+      151,
+      5
+    ],
+    [
+      519,
+      133,
+      6
+    ],
+    [
+      148,
+      512,
+      2
+    ],
+    [
+      136,
+      512,
+      2
+    ],
+    [
+      103,
+      133,
+      4
+    ],
+    [
+      176,
+      132,
+      2
+    ],
+    [
+      168,
+      168,
+      2
+    ],
+    [
+      519,
+      149,
+      6
+    ],
+    [
+      519,
+      146,
+      6
+    ],
+    [
+      525,
+      172,
+      5
+    ],
+    [
+      313,
+      313,
+      2
+    ],
+    [
+      526,
+      163,
+      2
+    ],
+    [
+      521,
+      104,
+      4
+    ],
+    [
+      136,
+      136,
+      6
+    ],
+    [
+      170,
+      170,
+      4
+    ],
+    [
+      524,
+      133,
+      4
+    ],
+    [
+      519,
+      147,
+      6
+    ],
+    [
+      525,
+      165,
+      5
+    ],
+    [
+      525,
+      173,
+      5
+    ],
+    [
+      138,
+      138,
+      6
+    ],
+    [
+      166,
+      158,
+      1
+    ],
+    [
+      41,
+      41,
+      2
+    ],
+    [
+      527,
+      156,
+      6
+    ],
+    [
+      524,
+      147,
+      4
+    ],
+    [
+      240,
+      240,
+      2
+    ],
+    [
+      149,
+      512,
+      2
+    ],
+    [
+      154,
+      154,
+      3
+    ],
+    [
+      103,
+      146,
+      4
+    ],
+    [
+      525,
+      180,
+      5
+    ],
+    [
+      163,
+      513,
+      1
+    ],
+    [
+      519,
+      138,
+      6
+    ],
+    [
+      150,
+      150,
+      5
+    ],
+    [
+      524,
+      146,
+      4
+    ],
+    [
+      532,
+      152,
+      7
+    ],
+    [
+      189,
+      133,
+      2
+    ],
+    [
+      132,
+      146,
+      2
+    ],
+    [
+      524,
+      145,
+      4
+    ],
+    [
+      163,
+      152,
+      3
+    ],
+    [
+      525,
+      181,
+      5
+    ],
+    [
+      217,
+      217,
+      2
+    ],
+    [
+      156,
+      156,
+      2
+    ],
+    [
+      524,
+      144,
+      4
+    ],
+    [
+      146,
+      132,
+      2
+    ],
+    [
+      147,
+      133,
+      2
+    ],
+    [
+      514,
+      132,
+      3
+    ],
+    [
+      158,
+      173,
+      2
+    ],
+    [
+      145,
+      149,
+      2
+    ],
+    [
+      35,
+      35,
+      2
+    ],
+    [
+      105,
+      105,
+      3
+    ],
+    [
+      242,
+      242,
+      2
+    ],
+    [
+      527,
+      163,
+      6
+    ],
+    [
+      219,
+      219,
+      2
+    ],
+    [
+      103,
+      147,
+      4
+    ],
+    [
+      236,
+      236,
+      2
+    ],
+    [
+      514,
+      136,
+      3
+    ],
+    [
+      104,
+      167,
+      1
+    ],
+    [
+      314,
+      314,
+      2
+    ],
+    [
+      526,
+      168,
+      2
+    ],
+    [
+      132,
+      149,
+      2
+    ],
+    [
+      151,
+      151,
+      2
+    ],
+    [
+      527,
+      158,
+      6
+    ],
+    [
+      132,
+      147,
+      2
+    ],
+    [
+      148,
+      133,
+      2
+    ],
+    [
+      514,
+      138,
+      3
+    ],
+    [
+      527,
+      168,
+      6
+    ],
+    [
+      525,
+      166,
+      5
+    ],
+    [
+      176,
+      145,
+      2
+    ],
+    [
+      361,
+      361,
+      2
+    ],
+    [
+      519,
+      145,
+      6
+    ],
+    [
+      146,
+      136,
+      2
+    ],
+    [
+      132,
+      136,
+      2
+    ],
+    [
+      527,
+      170,
+      6
+    ],
+    [
+      180,
+      168,
+      2
+    ],
+    [
+      146,
+      133,
+      2
+    ],
+    [
+      165,
+      165,
+      4
+    ],
+    [
+      170,
+      104,
+      1
+    ],
+    [
+      82,
+      82,
+      2
+    ],
+    [
+      246,
+      246,
+      2
+    ],
+    [
+      132,
+      138,
+      2
+    ],
+    [
+      532,
+      156,
+      7
+    ],
+    [
+      147,
+      144,
+      2
+    ],
+    [
+      158,
+      158,
+      2
+    ],
+    [
+      514,
+      148,
+      3
+    ],
+    [
+      526,
+      170,
+      2
+    ],
+    [
+      345,
+      345,
+      2
+    ],
+    [
+      514,
+      149,
+      3
+    ],
+    [
+      147,
+      138,
+      2
+    ],
+    [
+      517,
+      512,
+      3
+    ],
+    [
+      163,
+      163,
+      5
+    ],
+    [
+      514,
+      150,
+      3
+    ],
+    [
+      223,
+      223,
+      2
+    ],
+    [
+      166,
+      166,
+      4
+    ],
+    [
+      523,
+      147,
+      4
+    ],
+    [
+      136,
+      146,
+      2
+    ],
+    [
+      526,
+      152,
+      2
+    ],
+    [
+      132,
+      148,
+      2
+    ],
+    [
+      165,
+      156,
+      1
+    ],
+    [
+      206,
+      206,
+      2
+    ],
+    [
+      524,
+      136,
+      4
+    ],
+    [
+      514,
+      145,
+      3
+    ],
+    [
+      366,
+      366,
+      2
+    ],
+    [
+      519,
+      151,
+      6
+    ],
+    [
+      136,
+      133,
+      2
+    ],
+    [
+      104,
+      168,
+      2
+    ],
+    [
+      222,
+      222,
+      3
+    ],
+    [
+      523,
+      132,
+      4
+    ],
+    [
+      524,
+      138,
+      4
+    ],
+    [
+      170,
+      152,
+      1
+    ],
+    [
+      40,
+      40,
+      2
+    ],
+    [
+      181,
+      181,
+      4
+    ],
+    [
+      173,
+      173,
+      3
+    ],
+    [
+      328,
+      328,
+      2
+    ],
+    [
+      145,
+      512,
+      2
+    ],
+    [
+      517,
+      103,
+      3
+    ],
+    [
+      514,
+      545,
+      1
+    ],
+    [
+      526,
+      156,
+      2
+    ],
+    [
+      150,
+      150,
+      2
+    ],
+    [
+      517,
+      176,
+      6
+    ],
+    [
+      514,
+      146,
+      3
+    ],
+    [
+      167,
+      167,
+      3
+    ],
+    [
+      146,
+      144,
+      2
+    ],
+    [
+      532,
+      168,
+      7
+    ],
+    [
+      138,
+      177,
+      2
+    ],
+    [
+      149,
+      149,
+      7
+    ],
+    [
+      103,
+      103,
+      3
+    ],
+    [
+      316,
+      316,
+      2
+    ],
+    [
+      519,
+      150,
+      6
+    ],
+    [
+      532,
+      163,
+      7
+    ],
+    [
+      532,
+      158,
+      7
+    ],
+    [
+      514,
+      151,
+      3
+    ],
+    [
+      138,
+      147,
+      2
+    ]
+  ]
+}

variants/extended-1st-10mm-1k/profiles/eef/config.json

@@ -0,0 +1,4 @@
+{
+  "model_type": "actioncodec2_unified",
+  "processor_class": "ActionCodec2Processor"
+}

variants/extended-1st-10mm-1k/profiles/eef/config.yaml

@@ -0,0 +1,74 @@
+model_type: actioncodec2_unified
+config_version: 1
+physical:
+  input_dim: 7
+  components:
+    translation_m:
+      dims:
+        start: 0
+        stop: 3
+      space: additive
+      input_order: 0
+      primitive_order: 1
+      input_transform:
+        scale: 1.0
+        clip: false
+      constraints:
+        order_0:
+          min: -2.0
+          max: 2.0
+        order_1:
+          min: -0.08
+          max: 0.08
+      distortion_limit: 0.01
+      primitive_selection: smooth
+    orientation_so3:
+      dims:
+        start: 3
+        stop: 6
+      space: so3
+      input_order: 0
+      primitive_order: 1
+      input_transform:
+        scale: 1.0
+        clip: false
+      constraints:
+        order_0:
+          min: -3.141592653589793
+          max: 3.141592653589793
+        order_1:
+          min: -0.25
+          max: 0.25
+      distortion_limit: 0.04
+      primitive_selection: smooth
+      representation: rotation_vector
+      multiplication: right
+    gripper_open_command:
+      dims:
+      - 6
+      space: additive
+      input_order: 0
+      primitive_order: 0
+      input_transform:
+        scale: 1.0
+        clip: true
+      constraints:
+        order_0:
+          min: 0.0
+          max: 1.0
+      distortion_limit: 0.5
+      primitive_selection: nearest
+set_bpe:
+  lookahead: 8
+  allow_cross_component_merge: false
+train:
+  primitives:
+    zero_primitive_components:
+    - translation_m
+    - orientation_so3
+  bpe:
+    spatial_vocab_size: 512
+    vocab_size: 1024
+  quality_control:
+    hard_order_1_scale: 3.0
+    min_segment_length: 2