Merge branch 'feat/sdk-canonical-object-types' into 'internal_main'

RFC — SDK del MessageParser/DataSource para inversión ObjectStore (builtin-object types)

See merge request client-projets/p.2026-plotjuggler/plotjuggler_core!175

Author: pabloinigoblasco

CLAUDE.md

@@ -6,23 +6,43 @@ PlotJuggler Core — C++20 foundation libraries for PlotJuggler storage, plugin
 
 ### Modules
 
-- **pj_base** — vocabulary types, plugin ABI headers, plugin SDK headers (zero external deps)
+- **pj_base** — foundational SDK/ABI types, canonical builtin object vocabulary, plugin ABI headers,
+  host-view helpers, ImageAnnotations codec, and shared utilities
 - **pj_datastore** — columnar storage engine + `ObjectStore` (for media blobs) + `DerivedEngine` (fmt, tsl::robin_map, nanoarrow)
-- **pj_plugins** — C-ABI plugin protocol, C++ SDK base classes, plugin discovery, host-side loaders, config envelope helpers, and dialog protocol primitives; four plugin families: DataSource, MessageParser, Dialog, Toolbox
-- **pj_scene_protocol** — canonical schema + Foxglove `ImageAnnotations` Protobuf codec (writer + reader); SDK boundary for plugin authors producing or consuming 2D markers / scene primitives. `pj_base`-only deps.
+- **pj_plugins** — C++ plugin SDK base classes, plugin discovery, host-side loaders, config envelope
+  helpers, and dialog protocol primitives; four plugin families: DataSource, MessageParser, Dialog, Toolbox
 
 ### Dependency graph
 
 - `pj_datastore` → `pj_base`
 - `pj_plugins` → `pj_base`
-- `pj_scene_protocol` → `pj_base`
+
+## Documentation Workflow
+
+Coding agents should use this context hierarchy:
+
+```text
+CLAUDE.md -> relevant docs -> code
+```
+
+- Start with this file to identify the module and the relevant source-of-truth documents.
+- Read the relevant docs before treating code as authoritative for intent. Code shows current implementation
+  details; docs define the intended architecture, public contracts, terminology, and module boundaries.
+- If docs and code disagree, treat that as a documentation consistency problem. Do not silently let stale docs survive.
+- Any change to behavior, public APIs, ABI structs, SDK types, module ownership, plugin workflows,
+  storage formats, or user-facing semantics must include a documentation check.
+- Before any commit, verify that documentation is up to date for the change. If docs are stale and the user did
+  not explicitly ask for a docs update, ask whether to update the docs before committing. Do not commit
+  known-stale documentation.
 
 ## Key Documentation
 
 **Project-wide:**
 
 | Document | Content |
 |----------|---------|
+| `docs/builtin_type.md` | Canonical builtin object types used as the shim between third-party schemas and PlotJuggler internals |
+| `docs/image_annotations_format.md` | Canonical `PJ.ImageAnnotations` wire format for builtin `ImageAnnotations` payloads |
 | `docs/cpp_design_recommendations.md` | C++ style, error handling, API design guidelines |
 | `docs/toolbox-porting-gap-analysis.md` | SDK gaps identified when porting PJ3 toolboxes (being addressed) |
 
@@ -46,13 +66,6 @@ PlotJuggler Core — C++20 foundation libraries for PlotJuggler storage, plugin
 | `dialog-plugin-guide.md` | SDK tutorial: WidgetData, typed events, EmbedUi, requestAccept, onTick |
 | `toolbox-guide.md` | SDK tutorial: read+write access, catalog, notifyDataChanged |
 
-**Scene protocol** (`pj_scene_protocol/docs/`):
-
-| Document | Content |
-|----------|---------|
-| `ARCHITECTURE.md` | Wire format spec (`foxglove.ImageAnnotations` Protobuf), type catalog, encoding rules, design rationale (single canonical decoder, loader-side conversion) |
-| `USER_GUIDE.md` | Producer recipe (loader writing markers) and consumer recipe (sink/viewer decoding), common pitfalls, pointer to PJ4 reference adapters |
-
 ## Build & Test
 
 ```bash
@@ -65,18 +78,27 @@ Dependencies: Conan (`conanfile.txt`).
 
 ## Pre-commit Validation
 
+Before committing, first check whether the code changes require documentation updates. If documentation is stale
+and the requested task did not include updating it, ask the user whether to update the docs before committing.
+
 Before committing, always run:
 
 ```bash
-./build.sh --debug && ./test.sh && ./run_clang_tidy.sh
+./build.sh --debug && ./test.sh
 ```
 
+Code formatting and linting are enforced via pre-commit hooks (clang-format v17).
+
 ## Instructions Glossary
 
-- **"Read all documentation"** means: find and read every `.md` file in the entire project tree (all subdirectories). Use `find . -name "*.md"` or equivalent. This includes docs in `pj_base/`, `pj_datastore/docs/`, `pj_plugins/docs/`, `pj_scene_protocol/docs/`, and any other location.
+- **"Read all documentation"** means: find and read every `.md` file in the entire project tree (all subdirectories). Use `find . -name "*.md"` or equivalent. This includes docs in `docs/`, `pj_datastore/docs/`, `pj_plugins/docs/`, and any other location.
 
 - **"Update the documentation"** means: based on what you learned during this session, correct any documentation that is outdated or inaccurate, and clarify any ambiguity that caused confusion or errors. If a doc says one thing but the code does another, fix the doc to match reality. If missing information led to a bug, add it.
 
+- **"Check documentation"** means: review the docs listed above that are related to the changed module or API.
+  Confirm they still describe the current intent and behavior. If not, update them or ask the user before
+  committing.
+
 ## Coding Conventions
 
 - **Formatting:** Google style via `.clang-format` — 2-space indent, 120-char limit

CMakeLists.txt

@@ -159,7 +159,6 @@ if(PJ_BUILD_DATASTORE)
   add_subdirectory(pj_datastore)
 endif()
 add_subdirectory(pj_plugins)
-add_subdirectory(pj_scene_protocol)
 
 if(PJ_BUILD_PORTED_PLUGINS AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/pj_ported_plugins/CMakeLists.txt")
   set(PJ_HAS_PORTED_PLUGINS TRUE)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide Faconti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cmake/PlotJugglerSDKConfig.cmake.in

@@ -13,7 +13,6 @@ include("${CMAKE_CURRENT_LIST_DIR}/PlotJugglerSDKTargets.cmake")
 # Per-component validation.
 foreach(_comp ${PlotJugglerSDK_FIND_COMPONENTS})
   if(_comp STREQUAL "DataSource")
-    # No additional dependencies — pj_base is self-contained.
     set(PlotJugglerSDK_DataSource_FOUND TRUE)
 
   elseif(_comp STREQUAL "Dialog")