refactor(pj_base)!: remove the AssetVideo builtin object type (#131)

AssetVideo is superseded by the lazy PJ.VideoFrame path. The MP4 and
LeRobot loaders already produce VideoFrame, and nothing in the SDK,
PJ4, or pj-official-plugins (main) produces or consumes AssetVideo
anymore.

Remove the struct, codec, the PJ.AssetVideo .proto contract, and tests.
Drop the kAssetVideo (C++ BuiltinObjectType) and
PJ_BUILTIN_OBJECT_TYPE_ASSET_VIDEO (C ABI) enumerators, plus the
name()/parseBuiltinObjectType()/typeOf() arms. Slot 12 becomes a
permanently-reserved gap, mirroring the existing slot-2 reserve — ids
13..18 keep their values; nothing is renumbered. Anything classified as
type-id 12 now degrades to kNone and is rejected (the std::any
forward-compat path), never silently reinterpreted.

The ABI sentinel test loses its ==12 pin (the symbol is gone); the
existing ==11 and ==13 pins bracket the reserved hole, and this also
adds the previously-missing VoxelGrid ==18 sentinel. abi/baseline.abi is
unchanged (the codec is a static lib, not exported ABI; the enum is
header-only — abidiff shows no delta).

Docs updated: builtin_type.md, proto/pj/README.md, and both CLAUDE.md
files (type/codec counts 17->16 and 16->15; reserved-slot notes now list
2 and 12).

BREAKING CHANGE: removes a canonical builtin object schema. Per the SDK
versioning contract this warrants a MAJOR (1.0.0) bump. Version sources
are intentionally left at 0.10.0 in this commit — the maintainer will
cut the version together with the other breaking changes batched for
1.0.0.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: facontidavide

CLAUDE.md

@@ -15,9 +15,9 @@ two modules below have no own CLAUDE.md.
 ### Modules
 
 - **pj_base** — vocabulary types (`Timestamp`, `DatasetId`, `Expected<T>`, `Span<T>`, type trees),
-  the canonical builtin object vocabulary (`pj_base/builtin/`: 17 struct headers — Image, DepthImage,
-  PointCloud, CompressedPointCloud, OccupancyGrid(+Update), Mesh3D, VideoFrame, AssetVideo,
-  SceneEntities, RobotDescription, CameraInfo, Log, ImageAnnotations, FrameTransforms, PosesInFrame, VoxelGrid) and their 16
+  the canonical builtin object vocabulary (`pj_base/builtin/`: 16 struct headers — Image, DepthImage,
+  PointCloud, CompressedPointCloud, OccupancyGrid(+Update), Mesh3D, VideoFrame,
+  SceneEntities, RobotDescription, CameraInfo, Log, ImageAnnotations, FrameTransforms, PosesInFrame, VoxelGrid) and their 15
   wire codecs (RobotDescription carries source text as-is — no codec), the C-ABI protocol headers for
   DataSource/MessageParser/Toolbox + the C++ SDK base classes / host-view helpers built on them.
 - **pj_plugins** — host-side loaders + RAII handles + plugin discovery/catalog for four plugin

docs/builtin_type.md

@@ -22,7 +22,6 @@ The public headers live under:
 #include <pj_base/builtin/occupancy_grid.hpp>
 #include <pj_base/builtin/mesh3d.hpp>
 #include <pj_base/builtin/video_frame.hpp>
-#include <pj_base/builtin/asset_video.hpp>
 #include <pj_base/builtin/scene_entities.hpp>
 #include <pj_base/builtin/robot_description.hpp>
 #include <pj_base/builtin/image_annotations.hpp>
@@ -36,7 +35,6 @@ The public headers live under:
 #include <pj_base/builtin/occupancy_grid_codec.hpp>
 #include <pj_base/builtin/mesh3d_codec.hpp>
 #include <pj_base/builtin/video_frame_codec.hpp>
-#include <pj_base/builtin/asset_video_codec.hpp>
 #include <pj_base/builtin/scene_entities_codec.hpp>
 #include <pj_base/builtin/image_annotations_codec.hpp>
 #include <pj_base/builtin/frame_transforms_codec.hpp>
@@ -86,7 +84,7 @@ Builtin objects fall into two serialization families:
 | Family | Current types | Storage model | Codec policy |
 |--------|---------------|---------------|--------------|
 | Byte-backed views | `Image`, `DepthImage`, `PointCloud`, `CompressedPointCloud`, `OccupancyGrid`, `OccupancyGridUpdate`, `VoxelGrid`, `Mesh3D`, `VideoFrame` | Header fields live in the SDK struct; payload bytes live behind `Span<const uint8_t>` plus `BufferAnchor`. | No mandatory canonical codec; preserve zero-copy views over ROS, MCAP, compressed image, point-cloud, or plugin-owned payloads. If conversion is unavoidable, allocate a new payload and anchor it. |
-| Owned values | `ImageAnnotations`, `FrameTransforms`, `SceneEntities`, `AssetVideo`, `RobotDescription`, `CameraInfo`, `PosesInFrame`; future marker types | SDK structs own their vectors/strings/scalars directly. | Add explicit codecs when canonical bytes are needed. Codecs serialize the owned value to the protobuf-wire payload described by the `.proto` contract, using shared private wire primitives. `RobotDescription` carries source-format text as-is (no canonical codec) — the format hint distinguishes URDF / SDF / MJCF. |
+| Owned values | `ImageAnnotations`, `FrameTransforms`, `SceneEntities`, `RobotDescription`, `CameraInfo`, `PosesInFrame`; future marker types | SDK structs own their vectors/strings/scalars directly. | Add explicit codecs when canonical bytes are needed. Codecs serialize the owned value to the protobuf-wire payload described by the `.proto` contract, using shared private wire primitives. `RobotDescription` carries source-format text as-is (no canonical codec) — the format hint distinguishes URDF / SDF / MJCF. |
 
 Canonical `.proto` files live under `pj_base/proto/pj` and act as the wire
 format contract. One file per top-level message, each named after its message
@@ -120,7 +118,6 @@ annotations, frame transforms, or no builtin object.
 | `kMesh3D` | `PJ::sdk::Mesh3D` | 3D mesh asset in its native binary format (GLTF/GLB/STL/PLY/OBJ/USD/DAE). |
 | `kVideoFrame` | `PJ::sdk::VideoFrame` | One frame of an inter-frame-coded video stream (h264/h265/vp9/av1). |
 | `kSceneEntities` | `PJ::sdk::SceneEntities` | Procedural 3D scene primitives (arrows, cubes, lines, text, …). |
-| `kAssetVideo` | `PJ::sdk::AssetVideo` | File-backed video reference plus typed playback metadata. |
 | `kRobotDescription` | `PJ::sdk::RobotDescription` | Raw URDF/SDF/MJCF text + format hint. |
 | `kCameraInfo` | `PJ::sdk::CameraInfo` | Pinhole camera calibration (intrinsics K, distortion D, rectification R, projection P). |
 | `kOccupancyGridUpdate` | `PJ::sdk::OccupancyGridUpdate` | Incremental sub-rectangle patch for a previously-published `OccupancyGrid`. |
@@ -421,44 +418,6 @@ frames within a stream.
 `pj_base/builtin/video_frame_codec.hpp` serializes and deserializes this
 type using the canonical `PJ.VideoFrame` protobuf wire format.
 
-## AssetVideo
-
-`AssetVideo` is the entry-point handle for video assets ingested by data
-loaders that point at an external media file — LeRobot datasets, MP4
-loaders, and similar. Producers push exactly one `AssetVideo` per topic;
-the ObjectStore timestamp of that entry equals `time_origin_ns` so
-timeline UIs naturally see the asset's start instant.
-
-Unlike `VideoFrame` (a single frame of a streamed payload), `AssetVideo`
-carries no pixel data — it references the file by path and surfaces
-decode-routing metadata (media type, dimensions, frame rate) without
-forcing the consumer to open the file just to size a playback window.
-
-| Field | Type | Notes |
-|-------|------|-------|
-| `time_origin_ns` | `std::optional<Timestamp>` | Wall-clock instant of the first frame. Absent means the asset is not aligned to wall clock. |
-| `start_ns` | `std::optional<int64_t>` | In-file offset (ns) where the playable window begins. Absent means "play from the start of the file". |
-| `end_ns` | `std::optional<int64_t>` | In-file offset (ns) where the playable window ends. Absent means "play to the end of the file". |
-| `file_path` | `std::string` | Absolute path or path relative to a consumer-known root. |
-| `media_type` | `std::string` | MIME type hint. Empty means probe the file. |
-| `width` | `uint32_t` | Pixel width. `0` means unknown. |
-| `height` | `uint32_t` | Pixel height. `0` means unknown. |
-| `frame_rate` | `double` | Nominal FPS. `0` or NaN means unknown. |
-
-When both `start_ns` and `end_ns` are absent the whole file is the playable
-window. When present, consumers must clamp seek requests to
-`[start_ns, end_ns]` and bound timeline UI to that range. This is how
-producers expose one clip out of a file that holds many concatenated
-clips — for example LeRobot v3.0, where a single MP4 per camera packs
-many episodes back-to-back and `[from_timestamp, to_timestamp]` in the
-episode metadata maps directly to `[start_ns, end_ns]`.
-
-The total file duration is *not* carried in the message — the decoder
-backend reports it.
-
-`pj_base/builtin/asset_video_codec.hpp` serializes and deserializes this
-type using the canonical `PJ.AssetVideo` protobuf wire format.
-
 ## SceneEntities
 
 `SceneEntities` is the workhorse for marker-style 3D visualization — the
@@ -640,7 +599,6 @@ using the canonical `PJ.VoxelGrid` protobuf wire format.
 | URDF / `visualization_msgs/Marker` mesh resource | `Mesh3D` | Embed `data` (with `format`) or point at `url`; preserve `pose` and `scale`. |
 | ROS `nav_msgs/Path`, marker arrays | `SceneEntities` | Map polylines to `LinePrimitive`, arrows to `ArrowPrimitive`, etc. |
 | H.264/H.265/VP9/AV1 stream frame | `VideoFrame` | Forward one frame's bitstream bytes plus the codec identifier. |
-| MP4 / MKV / AV1 dataset file | `AssetVideo` | Push once per topic with the file path and metadata; consumers seek into the file by tracker time. |
 | Detection or tracking message | `ImageAnnotations` | Convert boxes, points, circles, and labels into pixel-space primitives. |
 | ROS `tf2_msgs/TFMessage` | `FrameTransforms` | Convert transform batches into named parent/child frame relationships. |
 | ROS `geometry_msgs/PoseArray` | `PosesInFrame` | Forward timestamp, frame, and the pose array; the viewer chooses how to draw them. |

pj_base/CLAUDE.md

@@ -1,18 +1,18 @@
 # pj_base — SDK vocabulary, builtin object schemas, and the C plugin ABI
 
-pj_base is the **Level 0** foundation and the **SDK boundary** for plugin authors. It owns: the zero-dependency vocabulary types (`Timestamp`, `DatasetId`, `Range`, `Expected<T>`, `Span`, `TypeTree`); the canonical *builtin object* schemas (`sdk::Image`, `PointCloud`, `DepthImage`, `OccupancyGrid`, `VoxelGrid`, `FrameTransforms`, … — 17 types) **and 16 of their wire codecs** (RobotDescription has none); and the **C ABI** primitives every plugin family speaks (`plugin_data_api.h` + the service registry) plus the C-ABI protocol headers for **three** families — `data_source_protocol.h`, `message_parser_protocol.h`, `toolbox_protocol.h`. The **Dialog** protocol header is the exception: it lives in `pj_plugins/dialog_protocol/`, not here. It also ships the C++ SDK base classes for DataSource and Toolbox; the MessageParser and Dialog base classes live in `pj_plugins`. Builds as a STATIC lib with **zero public deps** — `fast_float` is a `BUILD_INTERFACE` private impl detail of `parseNumber`. Must NOT depend on `pj_datastore`, `pj_plugins`, Qt, or any Conan runtime lib. This is a read-only submodule subtree: change it only when explicitly working in `plotjuggler_sdk`.
+pj_base is the **Level 0** foundation and the **SDK boundary** for plugin authors. It owns: the zero-dependency vocabulary types (`Timestamp`, `DatasetId`, `Range`, `Expected<T>`, `Span`, `TypeTree`); the canonical *builtin object* schemas (`sdk::Image`, `PointCloud`, `DepthImage`, `OccupancyGrid`, `VoxelGrid`, `FrameTransforms`, … — 16 types) **and 15 of their wire codecs** (RobotDescription has none); and the **C ABI** primitives every plugin family speaks (`plugin_data_api.h` + the service registry) plus the C-ABI protocol headers for **three** families — `data_source_protocol.h`, `message_parser_protocol.h`, `toolbox_protocol.h`. The **Dialog** protocol header is the exception: it lives in `pj_plugins/dialog_protocol/`, not here. It also ships the C++ SDK base classes for DataSource and Toolbox; the MessageParser and Dialog base classes live in `pj_plugins`. Builds as a STATIC lib with **zero public deps** — `fast_float` is a `BUILD_INTERFACE` private impl detail of `parseNumber`. Must NOT depend on `pj_datastore`, `pj_plugins`, Qt, or any Conan runtime lib. This is a read-only submodule subtree: change it only when explicitly working in `plotjuggler_sdk`.
 
 ## Layout
 - `include/pj_base/` — vocabulary primitives: `types.hpp`, `time.hpp` (absolute time spine: `Timepoint`/`Duration` + `fromRaw`/`toRaw`), `type_tree.hpp`, `dataset.hpp`, `expected.hpp`, `span.hpp`, `number_parse.hpp`, `assert.hpp`, `diagnostic_sink.hpp`, `buffer_anchor.hpp`.
-- `include/pj_base/builtin/` — the 17 builtin object struct headers (`*.hpp`; 18 enum values in `BuiltinObjectType`, value 2 reserved) + their 16 wire codecs (`*_codec.hpp`; RobotDescription has none) + the `BuiltinObject` (`std::any`) type-erased holder.
+- `include/pj_base/builtin/` — the 16 builtin object struct headers (`*.hpp`; 17 enum values in `BuiltinObjectType`, values 2 and 12 reserved) + their 15 wire codecs (`*_codec.hpp`; RobotDescription has none) + the `BuiltinObject` (`std::any`) type-erased holder.
 - `include/pj_base/sdk/` — C++ SDK over the ABI: DataSource + Toolbox `*_plugin_base.hpp`, `service_registry.hpp`/`service_traits.hpp`, host views, Arrow RAII holders, `testing/`.
 - `include/pj_base/*_protocol.h`, `plugin_data_api.h`, `builtin_object_abi.h`, `plugin_abi_export.hpp` — the stable C-ABI surface for DataSource/MessageParser/Toolbox (the Dialog protocol header lives in `pj_plugins/dialog_protocol/`).
 - `proto/pj/` — canonical `.proto` wire contracts for the builtin types (see its README).
 - `src/`, `tests/` — codec/parse impls and gtests.
 - `abi/baseline.abi` — golden libabigail dump; the ABI-stability regression baseline.
 
 ## Gotchas
-- ABI numbering is **frozen**: `BuiltinObjectType` (builtin_object.hpp) and `PJ_builtin_object_type_t` (builtin_object_abi.h) share stable numeric values — never renumber; type 2 is permanently reserved. Append-only.
+- ABI numbering is **frozen**: `BuiltinObjectType` (builtin_object.hpp) and `PJ_builtin_object_type_t` (builtin_object_abi.h) share stable numeric values — never renumber; types 2 and 12 are permanently reserved. Append-only.
 - Every vtable slot is `PJ_NOEXCEPT`; a throw across the ABI boundary calls `std::terminate`. See the header block in `plugin_data_api.h`.
 - `BuiltinObject` is `std::any`, deliberately not `std::variant`, for forward-compat — recover via `std::any_cast<T>` / `sdk::typeOf`. See `builtin/builtin_object.hpp`.
 - ABI/struct-layout or signature changes require a Conan **MINOR** bump and a refreshed `abi/baseline.abi`; tail-appended slots are a PATCH (see submodule CLAUDE.md → Release Versioning).

pj_base/CMakeLists.txt

@@ -3,7 +3,6 @@
 # ---------------------------------------------------------------------------
 
 add_library(pj_base STATIC
-  src/builtin/asset_video_codec.cpp
   src/builtin/camera_info_codec.cpp
   src/builtin/compressed_point_cloud_codec.cpp
   src/builtin/depth_image_codec.cpp
@@ -103,7 +102,6 @@ if(PJ_BUILD_TESTS)
     tests/mesh3d_codec_test.cpp
     tests/video_frame_codec_test.cpp
     tests/scene_entities_codec_test.cpp
-    tests/asset_video_codec_test.cpp
     tests/time_spine_test.cpp
     tests/poses_in_frame_codec_test.cpp
     tests/voxel_grid_codec_test.cpp

pj_base/include/pj_base/builtin/asset_video.hpp

@@ -26,7 +26,6 @@
 #include <optional>
 #include <string_view>
 
-#include "pj_base/builtin/asset_video.hpp"
 #include "pj_base/builtin/camera_info.hpp"
 #include "pj_base/builtin/compressed_point_cloud.hpp"
 #include "pj_base/builtin/depth_image.hpp"
@@ -59,7 +58,7 @@ enum class BuiltinObjectType : uint16_t {
   kMesh3D = 9,                ///< sdk::Mesh3D — binary mesh asset (GLTF/STL/PLY/OBJ/USD/DAE).
   kVideoFrame = 10,           ///< sdk::VideoFrame — single frame of h264/h265/vp9/av1 stream.
   kSceneEntities = 11,        ///< sdk::SceneEntities — procedural 3D scene primitives.
-  kAssetVideo = 12,           ///< sdk::AssetVideo — file-backed video reference + playback metadata.
+  // 12 reserved — was kAssetVideo (removed; video unified on kVideoFrame). Never reuse.
   kRobotDescription = 13,     ///< sdk::RobotDescription — raw URDF/SDF/MJCF text + format hint.
   kCameraInfo = 14,           ///< sdk::CameraInfo — pinhole camera calibration (K/D/R/P).
   kOccupancyGridUpdate = 15,  ///< sdk::OccupancyGridUpdate — incremental sub-rectangle patch for an OccupancyGrid.
@@ -100,8 +99,6 @@ struct SchemaClassification {
       return "kVideoFrame";
     case BuiltinObjectType::kSceneEntities:
       return "kSceneEntities";
-    case BuiltinObjectType::kAssetVideo:
-      return "kAssetVideo";
     case BuiltinObjectType::kRobotDescription:
       return "kRobotDescription";
     case BuiltinObjectType::kCameraInfo:
@@ -154,9 +151,6 @@ struct SchemaClassification {
   if (s == "kSceneEntities") {
     return BuiltinObjectType::kSceneEntities;
   }
-  if (s == "kAssetVideo") {
-    return BuiltinObjectType::kAssetVideo;
-  }
   if (s == "kRobotDescription") {
     return BuiltinObjectType::kRobotDescription;
   }
@@ -218,9 +212,6 @@ using BuiltinObject = std::any;
   if (t == typeid(SceneEntities)) {
     return BuiltinObjectType::kSceneEntities;
   }
-  if (t == typeid(AssetVideo)) {
-    return BuiltinObjectType::kAssetVideo;
-  }
   if (t == typeid(RobotDescription)) {
     return BuiltinObjectType::kRobotDescription;
   }

pj_base/include/pj_base/builtin/asset_video_codec.hpp

@@ -51,7 +51,7 @@ typedef enum PJ_builtin_object_type_t {
   PJ_BUILTIN_OBJECT_TYPE_MESH3D = 9,
   PJ_BUILTIN_OBJECT_TYPE_VIDEO_FRAME = 10,
   PJ_BUILTIN_OBJECT_TYPE_SCENE_ENTITIES = 11,
-  PJ_BUILTIN_OBJECT_TYPE_ASSET_VIDEO = 12,
+  /* 12 reserved — was PJ_BUILTIN_OBJECT_TYPE_ASSET_VIDEO (removed; video unified on VIDEO_FRAME). */
   PJ_BUILTIN_OBJECT_TYPE_ROBOT_DESCRIPTION = 13,
   PJ_BUILTIN_OBJECT_TYPE_CAMERA_INFO = 14,
   PJ_BUILTIN_OBJECT_TYPE_OCCUPANCY_GRID_UPDATE = 15,