chore: bump plugin ABI to v5

Author: Davide Faconti

cmake/PjAbiCheck.cmake

@@ -15,7 +15,7 @@
 #                          bumping PJ_ABI_VERSION for a major break).
 #
 # Baseline location: pj_base/abi/baseline.abi — the single source of
-# truth for what the v4 ABI looks like. The baseline is generated from
+# truth for what the current ABI looks like. The baseline is generated from
 # a canary plugin DSO (mock_data_source_plugin) whose symbol surface
 # exercises the full ABI header set via the SDK.
 #

cmake/PjPluginManifest.cmake

@@ -83,7 +83,7 @@ function(pj_emit_plugin_manifest TARGET)
 
   if(NOT ARG_ABI_MAJOR)
     # Matches PJ_ABI_VERSION in pj_base/plugin_data_api.h. Bump in lockstep.
-    set(ARG_ABI_MAJOR 4)
+    set(ARG_ABI_MAJOR 5)
   endif()
 
   # Track manifest edits so CMake reconfigures when the source changes.

pj_base/include/pj_base/builtin_object_abi.h

@@ -9,12 +9,12 @@
  *
  * Canonical-object production (any concrete sdk::* type listed in
  * BuiltinObjectType — see pj_base/builtin/builtin_object.hpp) and the
- * pure-functional scalar production (Expected<vector<NamedFieldValue>>)
- * are C++ SDK contracts: plugins inheriting from MessageParserPluginBase
- * register handlers in SchemaHandler, and the in-process host consumes
- * them via MessageParserPluginBase::parseObject() and parseScalars()
- * called directly on the C++ pointer. Pure-C plugins emit scalars via
- * the parse() slot (writing to writeHost).
+ * pure-functional scalar production (Expected<ObjectRecord> /
+ * Expected<ScalarRecord>) are C++ SDK contracts: plugins inheriting from
+ * MessageParserPluginBase register handlers in SchemaHandler, and the
+ * in-process host consumes them via MessageParserPluginBase::parseObject()
+ * and parseScalars() called directly on the C++ pointer. Pure-C plugins
+ * emit scalars via the parse() slot (writing to writeHost).
  */
 // Copyright 2026 Davide Faconti
 // SPDX-License-Identifier: MIT

pj_base/include/pj_base/plugin_data_api.h

@@ -45,15 +45,20 @@ extern "C" {
  * (e.g. DataSource + Dialog in one .so) work without any extra ceremony.
  * Do not redefine it manually.
  *
- * v4 plugins advertise version 4. Data-plane changes from the pre-v4 design:
+ * v5 plugins advertise version 5. Relative to v4, this bump rejects
+ * pre-v5 parser DSOs because the C++ MessageParserPluginBase
+ * pure-functional contract changed parseScalars()/parseObject() return
+ * types to ScalarRecord/ObjectRecord.
+ *
+ * The C data-plane layout remains the v4 layout:
  *   - Arrow C Data Interface replaces Arrow IPC bytes at the boundary
  *     (append_arrow_stream + read_series_arrow).
  *   - append_arrow_ipc removed from all write hosts.
  *   - read_series (PJ_materialized_series_t) removed from toolbox host.
  *   - Every vtable slot is PJ_NOEXCEPT.
  *   - Every slot carries a thread-class tag (// [main-thread], etc.).
  */
-#define PJ_ABI_VERSION 4
+#define PJ_ABI_VERSION 5
 
 /**
  * Convention for plugin-loaders:
@@ -90,13 +95,13 @@ typedef enum {
   PJ_PRIMITIVE_TYPE_UNSPECIFIED = 0xFF,
 } PJ_primitive_type_t;
 
-/* ABI-FROZEN: layout permanent; changes = v4 break. */
+/* ABI-FROZEN: layout permanent; changes = ABI break. */
 typedef struct {
   const char* data;
   size_t size;
 } PJ_string_view_t;
 
-/* ABI-FROZEN: layout permanent; changes = v4 break. */
+/* ABI-FROZEN: layout permanent; changes = ABI break. */
 typedef struct {
   const uint8_t* data;
   size_t size;
@@ -162,17 +167,17 @@ struct ArrowArrayStream {
 
 #endif /* ARROW_C_DATA_INTERFACE */
 
-/* ABI-FROZEN: layout permanent; changes = v4 break. */
+/* ABI-FROZEN: layout permanent; changes = ABI break. */
 typedef struct {
   uint32_t id;
 } PJ_data_source_handle_t;
 
-/* ABI-FROZEN: layout permanent; changes = v4 break. */
+/* ABI-FROZEN: layout permanent; changes = ABI break. */
 typedef struct {
   uint32_t id;
 } PJ_topic_handle_t;
 
-/* ABI-FROZEN: layout permanent; changes = v4 break. */
+/* ABI-FROZEN: layout permanent; changes = ABI break. */
 typedef struct {
   PJ_topic_handle_t topic;
   uint32_t id;
@@ -506,7 +511,7 @@ typedef struct {
  * `pj.parser_object_write.v1` in addition to `pj.parser_write.v1`.
  * ========================================================================== */
 
-/* ABI-FROZEN: layout permanent; changes = v5 break. */
+/* ABI-FROZEN: layout permanent; changes = ABI break. */
 typedef struct {
   uint32_t id; /* 0 == invalid handle */
 } PJ_object_topic_handle_t;

pj_base/tests/abi_layout_sentinels_test.cpp

@@ -1,10 +1,10 @@
 /**
  * @file abi_layout_sentinels_test.cpp
- * @brief Compile-time sentinels that pin the v4 plugin ABI layout.
+ * @brief Compile-time sentinels that pin the plugin C ABI layout.
  *
  * Every assertion here is a static_assert. A failure at compile time means
  * a struct defined in the ABI-visible headers has shifted in a way that
- * would silently break binary compatibility with existing v4 plugins.
+ * would silently break binary compatibility with existing plugins.
  *
  * Maintenance rule:
  *   - Sizes and alignments are allowed to GROW at the tail (new slots
@@ -16,7 +16,8 @@
  *     break.
  *   - MIN-size constants (PJ_*_MIN_VTABLE_SIZE) MUST NEVER INCREASE
  *     within a major version. They are pinned at v4.0 release and are
- *     the floor that forward compatibility relies on within the v4 series.
+ *     the floor that forward compatibility relies on within the current
+ *     major series.
  *
  * Pinning target: x86-64 System V (Linux/macOS on Intel/AMD). For other
  * ABIs (ARM64, MSVC), either confirm identical layout during initial
@@ -63,7 +64,7 @@ static_assert(sizeof(PJ_borrowed_dialog_t) == 16, "PJ_borrowed_dialog_t fat poin
 
 // --- DataSource vtable (ABI-APPENDABLE within v4) ----------------------------
 // Offsets of v4.0 slots: PINNED. sizeof and MIN_VTABLE_SIZE are allowed to
-// grow at the tail via future appends within the v4 series.
+// grow at the tail via future appends within the current major series.
 static_assert(offsetof(PJ_data_source_vtable_t, protocol_version) == 0, "v4 prefix pinned");
 static_assert(offsetof(PJ_data_source_vtable_t, struct_size) == 4, "v4 prefix pinned");
 static_assert(offsetof(PJ_data_source_vtable_t, bind) == 40, "v4 bind slot pinned");
@@ -174,7 +175,7 @@ static_assert(offsetof(PJ_toolbox_host_vtable_t, read_series_arrow) == 64, "tool
 static_assert(sizeof(PJ_toolbox_host_vtable_t) == 72, "Toolbox host size");
 
 // --- ABI version symbol ------------------------------------------------------
-static_assert(PJ_ABI_VERSION == 4, "v4 ABI version");
+static_assert(PJ_ABI_VERSION == 5, "v5 ABI version");
 
 // This translation unit has no runtime behavior; the above are all
 // compile-time assertions. Linking only confirms the TU compiled.

pj_plugins/docs/ARCHITECTURE.md

@@ -1,9 +1,9 @@
 # Plugin System Architecture
 
-## 0a. ABI stability and evolution rules (v4)
+## 0a. ABI stability and evolution rules (v5)
 
 Seven rules the loader and every plugin author rely on. Breaking any of
-these is an ABI break and requires a v5 bump.
+these is an ABI break and requires a future `PJ_ABI_VERSION` bump.
 
 1. **Boot-level ABI symbol.** Every plugin .so exports
    `pj_plugin_abi_version` as a `uint32_t` symbol independent of any
@@ -18,13 +18,13 @@ these is an ABI break and requires a v5 bump.
    duplicate definitions across translation units in one DSO, so a single
    .so can host multiple plugin families (e.g. DataSource + Dialog) with
    one `PJ_*_PLUGIN(...)` macro per family — no duplicate-symbol error.
-   Current value is `PJ_ABI_VERSION == 4`.
+   Current value is `PJ_ABI_VERSION == 5`.
 
 2. **Min-vtable-size floor, pinned at v4.0.** Each family header defines
    `PJ_<FAMILY>_MIN_VTABLE_SIZE` — the byte count of the vtable as
    shipped in v4.0. The loader accepts
    `struct_size >= MIN_VTABLE_SIZE`. This constant MUST NEVER GROW
-   within the v4 series. Growing it would reject plugins compiled
+   within a major series. Growing it would reject plugins compiled
    against older v4 headers (which correctly report a smaller size),
    silently breaking the forward-compatibility promise.
 
@@ -40,7 +40,7 @@ these is an ABI break and requires a v5 bump.
    - **ABI-FROZEN**: `PJ_error_t`, `PJ_string_view_t`, `PJ_bytes_view_t`,
      `PJ_borrowed_dialog_t`, `PJ_service_t`, `PJ_service_registry_t`,
      handle types, primitive-value unions. Layout permanent; any change
-     is a v4 break. `PJ_error_t` has `extended` + `extended_kind` slots
+     is an ABI break. `PJ_error_t` has `extended` + `extended_kind` slots
      reserved as its one growth path — do not add further top-level
      fields.
    - **ABI-APPENDABLE**: all `*_vtable_t` types, service-host vtables,
@@ -101,10 +101,11 @@ for known ids or `nullptr`. Hosts call via `handle.getPluginExtension(id)`
 (tail-slot-gated). Use the experimental namespace for work-in-progress
 extensions; graduate to stable (`pj.<name>.v1`) once locked in.
 
-## 0. Protocol v4 (current)
+## 0. C protocol v4 (current under ABI v5)
 
-All four plugin families (DataSource, MessageParser, Toolbox, Dialog) track
-protocol v4. Key v4 distinguishing features (a superset of everything the
+All four plugin families (DataSource, MessageParser, Toolbox, Dialog) keep
+the v4 C protocol layouts under the v5 boot ABI. Key v4 distinguishing
+features (a superset of everything the
 previously-circulated pre-v4 design included):
 
 - **Arrow C Data Interface at the data boundary.** The write-host

pj_plugins/docs/data-source-guide.md

@@ -1,6 +1,6 @@
 # Writing a DataSource Plugin
 
-> **Tracks the v4 plugin ABI** (`PJ_ABI_VERSION == 4`). For the full
+> **Tracks the v5 plugin ABI** (`PJ_ABI_VERSION == 5`). For the full
 > evolution rules (tail-slot gating, MIN_VTABLE_SIZE, ABI-FROZEN vs
 > ABI-APPENDABLE structs, Arrow C Data Interface at the write boundary,
 > PJ_NOEXCEPT discipline) see `ARCHITECTURE.md`. This guide walks

pj_plugins/docs/dialog-plugin-guide.md

@@ -1,6 +1,6 @@
 # Writing a Dialog Plugin
 
-> **Tracks the v4 plugin ABI** (`PJ_ABI_VERSION == 4`). Every dialog
+> **Tracks the v5 plugin ABI** (`PJ_ABI_VERSION == 5`). Every dialog
 > vtable slot is `PJ_NOEXCEPT` — the SDK trampolines in
 > `DialogPluginBase` catch exceptions automatically, but your overrides
 > must assume no exception ever crosses the ABI boundary. All dialog

pj_plugins/docs/message-parser-guide.md

@@ -1,6 +1,6 @@
 # Writing a MessageParser Plugin
 
-> **Tracks the v4 plugin ABI** (`PJ_ABI_VERSION == 4`). The parser
+> **Tracks the v5 plugin ABI** (`PJ_ABI_VERSION == 5`). The parser
 > write-host supports per-record writes and an optional Arrow stream
 > batch path for parser-shaped formats that naturally decode batches.
 > For ABI evolution rules, error semantics, and noexcept discipline see
@@ -534,21 +534,18 @@ depth image, point cloud, image annotations, frame transforms) returned by name
 from the parser, decoded once, and visualised by widgets that never learn the
 wire format.
 
-Three optional virtual entry points on `MessageParserPluginBase`
+The table-driven `SchemaHandler` routes on `MessageParserPluginBase`
 participate:
 
 ```cpp
-// In your subclass — every override is optional. The base provides
-// safe `unexpected(...)` defaults so legacy parsers compile unchanged.
-PJ::Expected<PJ::sdk::SchemaClassification>
-classifySchema(std::string_view type_name,
-               PJ::Span<const uint8_t> schema) override;
-
-PJ::Expected<std::vector<PJ::sdk::NamedFieldValue>>
-parseScalars(PJ::Timestamp ts, PJ::sdk::PayloadView payload) override;
-
-PJ::Expected<PJ::sdk::BuiltinObject>
-parseObject(PJ::Timestamp ts, PJ::sdk::PayloadView payload) override;
+PJ::sdk::SchemaHandler handler;
+handler.object_type = PJ::sdk::BuiltinObjectType::kImage;
+handler.parse_scalars =
+    [](PJ::Timestamp ts, PJ::Span<const uint8_t> payload)
+        -> PJ::Expected<PJ::sdk::ScalarRecord> { /* ... */ };
+handler.parse_object =
+    [](PJ::Timestamp ts, PJ::sdk::PayloadView payload)
+        -> PJ::Expected<PJ::sdk::ObjectRecord> { /* ... */ };
 ```
 
 - `classifySchema` is the *a-priori* declaration — given a type name +
@@ -557,12 +554,13 @@ parseObject(PJ::Timestamp ts, PJ::sdk::PayloadView payload) override;
   `kNone`) this schema produces. The host consults the answer **before** it
   ever sees the payload, so it can pick the right `ObjectIngestPolicy` for the
   topic.
-- `parseScalars` writes the small-metadata fields (`width`, `height`,
-  `frame_id`, …) that should land in the curve tree as scalar columns.
-- `parseObject` returns the actual builtin value, type-erased as
-  `PJ::sdk::BuiltinObject` (which is `std::any`). The host downcasts
-  with `std::any_cast<PJ::sdk::Image>(&obj)` to dispatch to the
-  matching viewer.
+- `parse_scalars` returns a `ScalarRecord`: small-metadata fields
+  (`width`, `height`, `frame_id`, …) plus an optional parser-controlled
+  timestamp.
+- `parse_object` returns an `ObjectRecord`: the actual builtin value,
+  type-erased as `PJ::sdk::BuiltinObject` (which is `std::any`), plus an
+  optional parser-controlled timestamp. The host downcasts with
+  `std::any_cast<PJ::sdk::Image>(&obj)` to dispatch to the matching viewer.
 
 Builtin types live under `pj_base/builtin/`, one header per
 type. `sdk::Image` carries an open-ended `std::string encoding`

pj_plugins/docs/toolbox-guide.md

@@ -1,6 +1,6 @@
 # Writing a Toolbox Plugin
 
-> **Tracks the v4 plugin ABI** (`PJ_ABI_VERSION == 4`). Toolbox plugins
+> **Tracks the v5 plugin ABI** (`PJ_ABI_VERSION == 5`). Toolbox plugins
 > read time series via the host's `read_series_arrow` slot, which
 > returns a caller-owned `ArrowSchema` + `ArrowArray` pair (no more
 > materialised `std::vector`). Wrap returns in