feat(plugin): reference-only entity designation on the HostApi (API v9)

The HostApi gains set_reference_only(handle, reference_only): a plugin can
designate display geometry it owns and refreshes. The entity renders like any
other, but the built-in edit paths treat it like an entity on a locked layer,
while the owning plugin keeps full write access (update, erase, XDATA).

- Appended at the trait tail with a refusing default so plugins keep compiling
  against older hosts; the loader gate range is untouched.
- IPC: SetReferenceOnly / SetReferenceOnlyResult round-trip through the
  shared dispatch, the V3 client and the V4 client, with the shared document
  cache invalidated on success.
- build.rs version_info and manifest API_VERSION bumped to 9 in lockstep.
- Evidence: reference_only_request_and_response_roundtrip (bincode round-trip
  of the request and both response payloads).

crates/ocs_plugin_api/src/ipc/client.rs

@@ -692,6 +692,23 @@ impl HostApi for PluginHostApi {
             Err(error) => Err(error.to_string()),
         }
     }
+
+    fn set_reference_only(&mut self, handle: Handle, reference_only: bool) -> Result<(), String> {
+        match self.client.request(PluginRequest::SetReferenceOnly {
+            handle,
+            reference_only,
+        }) {
+            Ok(PluginResponse::SetReferenceOnlyResult(result)) => {
+                if result.is_ok() {
+                    self.document_cache = OnceCell::new();
+                }
+                result
+            }
+            Ok(PluginResponse::Error(error)) => Err(error),
+            Ok(other) => Err(format!("unexpected reference-only response: {other:?}")),
+            Err(error) => Err(error.to_string()),
+        }
+    }
 }
 
 /// Sentinel reader used when the shared-memory view could not be initialized.

crates/ocs_plugin_api/src/ipc/protocol.rs

@@ -226,6 +226,11 @@ pub enum PluginRequest {
     ListXRecords {
         dictionary_path: Vec<String>,
     },
+    /// V9 (additive): mark an entity reference-only (plugin-owned display data).
+    SetReferenceOnly {
+        handle: Handle,
+        reference_only: bool,
+    },
 }
 
 /// Responses the host sends back for `PluginRequest`.
@@ -272,6 +277,8 @@ pub enum PluginResponse {
     XRecordDeleteResult(Result<crate::host::XRecord, String>),
     /// V8 (additive): XRecord names under a dictionary path.
     XRecordNames(Result<Vec<String>, String>),
+    /// V9 (additive): outcome of the reference-only designation.
+    SetReferenceOnlyResult(Result<(), String>),
 }
 
 /// Messages sent from the host to the plugin runner.

crates/ocs_plugin_api/src/ipc/server.rs

@@ -151,5 +151,11 @@ pub fn handle_plugin_request(
             let path: Vec<&str> = dictionary_path.iter().map(String::as_str).collect();
             PluginResponse::XRecordNames(host.list_xrecords(&path))
         }
+        SetReferenceOnly {
+            handle,
+            reference_only,
+        } => {
+            PluginResponse::SetReferenceOnlyResult(host.set_reference_only(handle, reference_only))
+        }
     }
 }

crates/ocs_plugin_api/src/ipc/v4/client.rs

@@ -987,6 +987,23 @@ impl HostApi for V4PluginHostApi {
             Err(error) => Err(error.to_string()),
         }
     }
+
+    fn set_reference_only(&mut self, handle: Handle, reference_only: bool) -> Result<(), String> {
+        match self.request(PluginRequest::SetReferenceOnly {
+            handle,
+            reference_only,
+        }) {
+            Ok(PluginResponse::SetReferenceOnlyResult(result)) => {
+                if result.is_ok() {
+                    self.document_cache = OnceCell::new();
+                }
+                result
+            }
+            Ok(PluginResponse::Error(error)) => Err(error),
+            Ok(other) => Err(format!("unexpected reference-only response: {other:?}")),
+            Err(error) => Err(error.to_string()),
+        }
+    }
 }
 
 #[cfg(test)]

crates/ocs_plugin_api/src/ipc/v4/protocol.rs

@@ -519,6 +519,47 @@ mod tests {
         }
     }
 
+    #[test]
+    fn reference_only_request_and_response_roundtrip() {
+        // The V9 request marks an entity reference-only and the response
+        // carries the operation's outcome.
+        let bytes = bincode::serialize(&PluginRequest::SetReferenceOnly {
+            handle: codec::Handle::new(0x2A),
+            reference_only: true,
+        })
+        .unwrap();
+        assert!(
+            matches!(bincode::deserialize::<PluginRequest>(&bytes).unwrap(),
+            PluginRequest::SetReferenceOnly { handle, reference_only } if
+                handle == codec::Handle::new(0x2A) && reference_only)
+        );
+        let bytes = bincode::serialize(&PluginRequest::SetReferenceOnly {
+            handle: codec::Handle::new(0x2A),
+            reference_only: false,
+        })
+        .unwrap();
+        assert!(matches!(
+            bincode::deserialize::<PluginRequest>(&bytes).unwrap(),
+            PluginRequest::SetReferenceOnly {
+                reference_only: false,
+                ..
+            }
+        ));
+        let bytes = bincode::serialize(&PluginResponse::SetReferenceOnlyResult(Ok(()))).unwrap();
+        assert!(matches!(
+            bincode::deserialize::<PluginResponse>(&bytes).unwrap(),
+            PluginResponse::SetReferenceOnlyResult(Ok(()))
+        ));
+        let bytes = bincode::serialize(&PluginResponse::SetReferenceOnlyResult(Err(
+            "entity is on a locked layer".to_owned(),
+        )))
+        .unwrap();
+        assert!(
+            matches!(bincode::deserialize::<PluginResponse>(&bytes).unwrap(),
+            PluginResponse::SetReferenceOnlyResult(Err(error)) if error == "entity is on a locked layer")
+        );
+    }
+
     #[test]
     fn unknown_notification_deserializes_as_unknown() {
         // Build a payload with an unknown discriminant (99) followed by some