Merge PR #1028: add document API with atomic edits

Add the typed document facade and plugin IPC adapter. Prepare bulk edits
before mutation, preserve undo and dirty state, keep profile elevations,
validate numeric inputs and session bindings, and generate Python constructors
with typed results.

Reuse existing entity transforms and profile conversion. Compute mass
properties and closed-surface bounds in cadkernel; pin its main revision
6a5e6fc2822f6af6b2611cd605b44437b35158f0. Keep plugin API metadata at version 6.

Validation: 646 native application tests, 597 kernel tests, 12 document API
tests, 91 plugin API tests, 3 Python tests, default/IPC feature builds and
wasm32 check passed.

crates/ocs_doc_api/src/transport/inproc.rs

@@ -0,0 +1,42 @@
+//! In-process transport: drives a `DocApiBackend` directly, inline.
+//! Used by in-tree/built-in plugins and host tests. Thread-safe via a mutex so
+//! many handles across many threads share it (calls are serialized).
+
+use std::sync::Mutex;
+
+use crate::backend::DocApiBackend;
+use crate::envelope::{DocApiEnvelope, EnvelopeBody, Receipt};
+use crate::error::ApiResult;
+use crate::executor;
+use crate::transport::Transport;
+
+/// In-process transport: holds the backend behind a mutex (reentrant `&self`).
+pub struct InProcess<B: DocApiBackend> {
+    backend: Mutex<B>,
+}
+
+impl<B: DocApiBackend> InProcess<B> {
+    pub fn new(backend: B) -> Self {
+        Self {
+            backend: Mutex::new(backend),
+        }
+    }
+    /// Borrow the backend immutably (test/introspection helper).
+    pub fn backend(&self) -> std::sync::MutexGuard<'_, B> {
+        self.backend.lock().expect("in-process backend poisoned")
+    }
+}
+
+impl<B: DocApiBackend + Send> Transport for InProcess<B> {
+    fn apply(&self, req: DocApiEnvelope) -> ApiResult<Receipt> {
+        req.validate_version()?;
+        let mut backend = self
+            .backend
+            .lock()
+            .map_err(|_| crate::error::ApiError::Transport("in-process backend poisoned".into()))?;
+        match req.body {
+            EnvelopeBody::Op(op) => executor::apply_op(&mut *backend, op),
+            EnvelopeBody::Queries(queries) => executor::apply_queries(&mut *backend, queries),
+        }
+    }
+}

crates/ocs_doc_api/src/transport/ipc.rs

@@ -0,0 +1,58 @@
+//! IPC transport: serializes `DocApiEnvelope` into the
+//! append-only `PluginRequest::DocApiRequest { tab_id, bytes }` variant and ships
+//! it through the plugin's `PluginRequestSender`. The host routes that variant to
+//! the same crate executor (`ocs_doc_api::executor`) — one implementation.
+
+use std::sync::Arc;
+
+use ocs_plugin_api::host::{PluginRequestError, PluginRequestSender};
+use ocs_plugin_api::ipc::protocol::{PluginRequest, PluginResponse};
+
+use crate::envelope::{DocApiEnvelope, Receipt};
+use crate::error::{ApiError, ApiResult};
+use crate::transport::Transport;
+
+/// Out-of-process IPC transport over the `ocs_plugin_api` channel. `Send + Sync`;
+/// the underlying `PluginRequestSender` already serializes + correlates (V4).
+pub struct OcsPluginApiIpc {
+    sender: Arc<dyn PluginRequestSender>,
+    tab_id: u64,
+}
+
+impl OcsPluginApiIpc {
+    pub fn new(sender: Arc<dyn PluginRequestSender>, tab_id: u64) -> Self {
+        Self { sender, tab_id }
+    }
+
+    fn transport_err(e: PluginRequestError) -> ApiError {
+        ApiError::Transport(e.0)
+    }
+}
+
+impl Transport for OcsPluginApiIpc {
+    fn apply(&self, req: DocApiEnvelope) -> ApiResult<Receipt> {
+        let bytes = bincode::serialize(&req)
+            .map_err(|e| ApiError::Transport(format!("envelope serialize: {e}")))?;
+        let resp = self
+            .sender
+            .request(PluginRequest::DocApiRequest {
+                tab_id: self.tab_id,
+                bytes,
+            })
+            .map_err(Self::transport_err)?;
+        match resp {
+            PluginResponse::DocApiResponse { bytes } => {
+                // The host serializes `ApiResult<Receipt>` so op/query errors
+                // (validation, geometry, unknown id) surface as the SAME
+                // structured `ApiError` the in-process executor produced.
+                let result: ApiResult<Receipt> = bincode::deserialize(&bytes)
+                    .map_err(|e| ApiError::Transport(format!("receipt deserialize: {e}")))?;
+                result
+            }
+            PluginResponse::Error(msg) => Err(ApiError::Transport(msg)),
+            other => Err(ApiError::Transport(format!(
+                "unexpected DocApi response variant: {other:?}"
+            ))),
+        }
+    }
+}

crates/ocs_doc_api/src/transport/mod.rs

@@ -0,0 +1,36 @@
+//! The transport boundary — the ONLY plugin↔host boundary.
+//!
+//! Portability contract (SPSC / flume / shared-memory safe): a transport impl
+//! must (a) accept `&self` calls from many threads and serialize sends internally,
+//! (b) demultiplex responses to the right caller by a correlation id, (c)
+//! block-with-timeout, (d) expose liveness. This matches the existing V4 channel
+//! shape, so swapping socket → shm changes only the impl, never the facade.
+
+#[cfg(feature = "host")]
+pub mod inproc;
+#[cfg(feature = "ipc")]
+pub mod ipc;
+
+#[cfg(feature = "host")]
+pub use inproc::InProcess;
+#[cfg(feature = "ipc")]
+pub use ipc::OcsPluginApiIpc;
+
+use crate::envelope::{DocApiEnvelope, Receipt};
+use crate::error::ApiResult;
+
+/// The only plugin↔host boundary. Object-centric: one method per unit of work —
+/// a single write op, or a query batch. `&self` + `Send + Sync` so many entity
+/// handles across many threads share one transport concurrently.
+pub trait Transport: Send + Sync {
+    /// Apply `req` (ONE write op, or a query batch) and return its `Receipt`.
+    /// A write request carries exactly one `Operation`; a read request carries
+    /// one-or-more `Query` items (read-only batching is safe). Blocks up to an
+    /// internal timeout. Reentrant: safe to call concurrently from many threads.
+    fn apply(&self, req: DocApiEnvelope) -> ApiResult<Receipt>;
+
+    /// Cheap host-liveness probe (shm has no socket-disconnect to detect a dead peer).
+    fn alive(&self) -> bool {
+        true
+    }
+}