OneCAD-Draft/crates/ocs_doc_api/ARCHITECTURE.md

ocs_doc_api — Architecture

This document explains how ocs_doc_api is put together and, most importantly, the workflow for adding a new entity, family, or method. It assumes you've read README.md (the user-facing surface).

Layered design

┌─ Facade (facade.rs)        DocApi → Document → collections → typed handles
│    Object-centric, hand-written. Methods build Operation/Query and call
│    Transport::apply. OpGroup (client compensation), query_batch, assert_revision.
│
├─ Wire (envelope/ops/query) DocApiEnvelope = Op(single) | Queries(batch)
│    bincode + serde. Operation/Query enums are GENERATED (src/gen) from the spec.
│    Append-only variants → stable discriminants.
│
├─ Transport (transport/)    trait Transport: Send+Sync { apply, alive }
│    InProcess (host) | OcsPluginApiIpc (plugin). The ONLY plugin↔host boundary.
│    Portability contract: &self + internal serialization + correlation + timeout.
│
├─ Executor (executor.rs)    apply_op / apply_queries  ← crate-owned logic
│    Per-op atomicity: validate+compute BEFORE push_undo; mutate; finalize_op once.
│
├─ Backend (backend.rs)      trait DocApiBackend  ← thin host hook
│    resolve_body / store_solid / update_solid / add_curve / transform_entity /
│    bounds / volume / centroid / revision / push_undo / finalize_op /
│    ensure_transformable / can_remove / ...
│
└─ Host (src/app/doc_api.rs) impl DocApiBackend for HostSession
     Maps to scene/app primitives: register_solid_model, restore_solid_models
     (lift-on-miss), solid_to_sat, edge_wires, erase_entities, meshes.metrics.

The same executor runs in-process and over IPC — one implementation, versioned in the crate. The host only supplies scene primitives through DocApiBackend.

Per-op execution model (the load-bearing invariant)

Every write op follows this exact sequence (see executor::apply_op):

1. Validate + compute — resolve inputs, run kernel geometry (make_solid, brep::combine, brep::transform), pre-flight fallible host work (prepare_solid_model_display), check ensure_transformable / can_remove. No mutation yet.
2. push_undo(label) — begin the host's undo delta capture.
3. Mutate — store_solid / update_solid / add_curve / transform_entity / remove_entity.
4. finalize_op() — close the undo delta + republish the document view.

On any error in steps 1–3, the op returns before finalize_op: nothing is applied, no undo step, no revision bump. This is the per-op atomicity guarantee. brep::combine is pure; erase_sources only runs on success.

The geometry revision advances via the host's internal bump_geometry inside add_entity/update_entity/register_prepared_solid_model. The epoch moves monotonically per op (one undo step per op); the exact bump count is a host internal — do not assert on it.

Object identity and the solid cache

• ObjectId = acadrust::Handle (u64). Kernel keys never cross the API.
• Solids live in the host's scene.solid_models: HashMap<Handle, Body> cache. resolve_body does lift-on-miss (restore_solid_models): if a solid isn't cached, its body is re-lifted from the entity's ACIS SAT. This is what makes DocApi-created solids visible to host-native booleans and vice versa, and what makes a reloaded DWG's solids usable.
• store_solid / update_solid pre-flight the mesh (prepare_solid_model_display) before committing, so the post-commit register_prepared_solid_model cannot fail — there is no rollback path that would bump the revision on failure.

Bulk ops and read batching

• CreateMany / TransformMany / DeleteMany are single ops, one undo step, one publish — but all-or-nothing via upfront validation: every fallible check (make_solid, ensure_transformable, can_remove) runs before push_undo, so the apply loop cannot fail part-way. Item-capped (BULK_ITEM_CAP) to bound host execution.
• Read-only query batching (query_batch) shares one round-trip and never bumps the revision. Also capped.
• Why: per-op publish_document_view is a full-document serialization, so N sequential ops cost O(N²) — bulk ops collapse that to O(N) once. See "Performance" below.

Codegen (build-time, spec-driven)

build.rs reads spec/entities.toml and regenerates the committed snapshots:

• src/gen/ops_gen.rs, src/gen/query_gen.rs — the Operation/Query enums (the canonical wire vocabulary; append new variants at the END only).
• src/gen/api_reference.md — human API reference.
• src/gen/binding_schema.json — the merged binding-handover schema (object model + method signatures + op/query mapping + wire layouts), exposed as binding_schema_json() for REPL/scripting bridges.

cargo build regenerates them deterministically; CI fails on drift.

---

Workflow: adding a new entity, family, or method

This is the common task. Follow these steps in order.

A. Add a new Operation or Query variant (the wire vocabulary)

1. Append the variant to src/gen/ops_gen.rs / src/gen/query_gen.rs at the END of the enum (never reorder — bincode discriminants are order-based). Use existing payload DTOs or add new plain-data mirrors in src/ops.rs / src/query.rs.
2. Add its name to Operation::op_name / Query::query_name in src/ops.rs / src/query.rs.
3. Regenerate: cargo build -p ocs_doc_api — the spec/schema pick up the wire change. Update src/gen/layouts.json so binding_schema.json stays self-contained.

B. Add a family (e.g. a new entity kind)

1. Spec — add a [[family]] block in spec/entities.toml (name, acadrust_variant, handle, collection, and its [[family.method]]s).
2. Handle type — add a handle!(NewType) line in facade.rs (gives it bounds/delete/transform + id()), plus HasId. Add family-specific methods as an impl NewType block if it has geometric actions.
3. Construction — add a create_* method on the right collection (SolidCollection/CurveCollection/EntityCollection) building the op.
4. Backend conversion — extend src/app/doc_api_convert.rs (curve_spec_to_entity, entity_kind_name, entity_bounds) to map the new acadrust EntityType variant.
5. Executor — if the family has a new op variant, add its arm to executor::apply_op.

C. Add a method to an existing family

1. Wire — if it's a new operation/query, do step A first. If it reuses an existing op (e.g. another boolean), skip to step 3.
2. Spec — add a [[family.method]] entry under the family (name, kind, op/query, args, returns, fixed fields).
3. Facade — add the method to the handle's impl block in facade.rs; it should build the Operation/Query and call session.apply_op / session.one_query, returning the typed result.
4. Executor + backend — if the op is new, implement its arm in executor::apply_op (driving DocApiBackend), and add/override the backend method in the host (src/app/doc_api.rs) mapping to the scene primitive.
5. Test — add a mock-backend unit test (tests/mock_backend.rs) and, for host-affecting ops, a HostSession integration test in src/app/doc_api.rs (model it on the existing roundtrip tests).

D. Keep the invariants

• Validate + compute before push_undo; never mutate in the validate phase.
• One undo step per op; finalize_op only on success.
• New op/query variants append at the end of the generated enums.
• Host geometry stays in the host (kernel keys never cross the wire); the wire carries ObjectIds and plain-data DTOs.

---

Error model

ApiError::{Validation, Geometry, UnknownId, Unsupported, Transport} — serializable, so IPC returns the same structured error the in-process executor produced. Bulk-op validation names the failing index. A stale handle's methods return UnknownId (structured), never a panic.

Performance notes

• Per-op publish (finalize_op → publish_document_view) is a full-document serialization; N sequential ops cost O(N²). This is the documented trade of per-op autocommit and the reason bulk ops exist. Measured estimate: ~10⁵ sequential creates+transforms ≈ minutes; the same as one CreateMany+TransformMany ≈ ~1 s. Use bulk ops for N ≳ a few hundred.
• volume/centroid serve from scene.meshes[handle].metrics when cached; the kernel-mesh divergence is a cold-cache fallback.
• resolve_body lift-on-miss is cheap when the cache is warm (no-op).
• IPC serializes the envelope once; the bytes fields use serde_bytes so the outer frame is a single length-prefixed copy.

---

Changes from the original design (review-driven)

The initial implementation was reviewed (/review) and refined in two rounds. This section records the concrete changes and why they were made, so the reasoning isn't lost. Tests are green after every change (592 host lib + 8 crate unit + 7 HostSession integration tests, incl. the regression tests added for the CRITICAL fixes).

Files introduced / modified in src/app/

The host-side integration lives in src/app/. Concretely:

New files

• src/app/doc_api.rs — the DocApiBackend implementation for HostSession (the thin host hook). Contains:
  • execute_doc_api(host, tab_id, bytes) — the dispatch entry: deserialize the DocApiEnvelope, run the crate executor, serialize ApiResult<Receipt>.
  • impl DocApiBackend for HostSession — resolve_body (lift-on-miss via restore_solid_models), store_solid/update_solid (pre-flight prepare_solid_model_display before commit → register_prepared_solid_model), add_curve, remove_entity (direct erase_entities + locked-layer error), can_remove, ensure_transformable, transform_entity, bounds (lift-on-miss for solids), volume/centroid (meshes.metrics cache + divergence fallback), revision, push_undo/finalize_op.
  • helpers obj_to_handle/handle_to_obj, kernel_placement, mesh_volume_centroid (single divergence-theorem helper).
  • 7 #[cfg(test)] integration tests (create/boolean/query roundtrip, unknown-id error, transform-many all-or-nothing, query-batch cap, 2D-entity roundtrip, geometric-methods roundtrip, DWG write→reload roundtrip).
• src/app/doc_api_convert.rs — acadrust EntityType ↔ DTO conversions: curve_spec_to_entity (Line/Circle/LwPolyline/Point from Curve2Spec), entity_kind_name, entity_bounds (per-family coarse bounds for non-solids).

Modified files

• src/app/mod.rs — registers the two new modules (doc_api, doc_api_convert), both gated #[cfg(not(target_arch = "wasm32"))].
• src/app/plugin_host.rs — extends HostSession:
  • a doc_api_pending: Option<PendingDelta> field (the in-flight per-op undo delta);
  • accessors used by the backend: scene()/scene_mut(), commit_entity_handle(entity) passthrough, begin_doc_api_undo(label) (→ app.begin_undo), commit_doc_api_undo() (→ app.commit_undo_delta + publish_document_view; no extra bump_geometry — the entity op already bumped);
  • impl HostApi for HostSession::doc_api_dispatch → routes to doc_api::execute_doc_api (gated not(wasm32)).

ocs_plugin_api (sibling crate, also touched)

• src/ipc/protocol.rs — appended PluginRequest::DocApiRequest{tab_id, bytes} and PluginResponse::DocApiResponse{bytes} (append-only; serde_bytes on the payload).
• src/host.rs — appended defaulted HostApi::doc_api_dispatch (returns "not supported"; HostSession overrides it). Append-only, object-safe.
• src/ipc/server.rs — routes DocApiRequest → host.doc_api_dispatch(...).

Review round 1 — correctness & safety fixes

Two CRITICAL and six WARNING findings were fixed:

1. Bulk ops are now truly all-or-nothing (was CRITICAL). The original TransformMany/DeleteMany/CreateMany only existence-checked ids; a mid-apply failure (e.g. store_solid register failure, or transform_entity hitting a non-solid) left partial state with no undo step. Now the executor pre-validates everything fallible before push_undo:

   • TransformMany → new backend method ensure_transformable(id) (v1: solids-only) validated for every id first.
   • DeleteMany → can_remove(id) (existence + not-on-locked-layer) for every id.
   • CreateMany → its prepare loop was already pure; the residual store_solid post-commit failure is eliminated by the pre-flight in (8).
   • Regression test: doc_api_transform_many_with_non_solid_fails_all_or_nothing.

2. Query batch is capped (was CRITICAL / DoS). apply_queries had no bound — a ≤64 MiB envelope could carry millions of GetVolume/GetCentroid queries, each tessellating a solid on the synchronous UI thread. Now capped at BULK_ITEM_CAP like the write bulk ops. Regression test: doc_api_query_batch_over_cap_is_rejected.

3. Locked-layer erase no longer silently succeeds (was WARNING). HostSession::remove_entity returns false for locked-layer entities; the executor treated Ok(false) as success (Delete reported Deleted, boolean erase_sources left the second input live). Now:

   • backend remove_entity returns Err(Unsupported) when the entity is on a locked layer;
   • the boolean-erase path validates can_remove(b) before update_solid(a);
   • Delete/DeleteMany pre-validate can_remove before push_undo.

4. One publish per op for deletes (was WARNING). The backend's remove_entity went through HostSession::remove_entity, which calls publish_document_view per invocation → DeleteMany triggered N+1 full-document publishes. The backend now calls scene.erase_entities directly (clears solid_models/meshes/hatches

   • records the undo delta); the single publish happens at finalize_op.

5. bounds lift-on-miss for solids (was WARNING). bounds checked solid_models.contains_key and fell through to a non-solid Unsupported for a solid with a cold cache (e.g. dropped by a host-side update_entity). Now it resolves solids through resolve_body (lift-on-miss), consistent with volume/centroid.

6. volume/centroid use the metrics cache (was WARNING / perf). They re-tessellated the full body (mesh_body) + cloned the B-rep per query. Now they serve from scene.meshes[handle].metrics when cached (refreshed on store/update), with the kernel-mesh divergence as a cold-cache fallback. The duplicated divergence loops were also merged into one mesh_volume_centroid.

7. Double revision bump documented (was WARNING). Solid write ops bump geometry_epoch twice (the entity add/update path + register_prepared_solid_model). This is host-internal and shared with native commands; the meaningful guarantee (one undo step per op, monotonic epoch) holds and is tested. Documented rather than changed, to avoid touching shared host scene bump behavior.

8. store_solid failure no longer moves the revision (was WARNING). The original rollback path (rollback_new_entities on register_solid_model failure) bumped the epoch again on a failed op, violating "failed op = no bump." Now store_solid/update_solid pre-flight prepare_solid_model_display before commit_entity_handle, so a mesh-prep failure errors before any mutation — the rollback path is eliminated (and the double prepare work is removed). This also feeds the CreateMany all-or-nothing guarantee in (1).

Review round 2 — cleanups (SUGGESTION)

• serde_bytes on the IPC payload — PluginRequest::DocApiRequest.bytes / PluginResponse::DocApiResponse.bytes now use #[serde(with = "serde_bytes")] so the outer frame is a single length-prefixed copy (was a per-byte seq walk + a second full copy on 10–20 MB bulk payloads).
• Dead code removed — src/gen/dispatch_gen.rs (never generated/included), Operation::references (no call sites, false doc comment), the discarded serde-reflection tracer stub + serde-reflection build-dep in build.rs (it reads layouts.json directly now), and the dead Session.tab field (transport carries tab_id; DocApi::document(tab) keeps the arg for forward-compat but no longer stores it).

Subsequent additions

• Rename ocs_doc_api_2 → ocs_doc_api (directory, package, lib, all refs). The plan document under .kilo/ keeps the historical name.
• DWG roundtrip robustness — the stable-DWG test writes to target/doc_api_roundtrip_intersected.dwg (kept for inspection). It releases a stale lock first and falls back to a process-unique path if still locked, so it never flakes on Windows file locking (error 33).
• Docs — README.md, this file, IMPLEMENTATION.md, enriched spec/entities.toml + the generated api_reference.md (constructors, generic methods, cross-cutting, bulk ops, unsupported markers).
• Examples — five runnable examples under examples/ (e1 primitives+queries, e2 booleans, e3 transform-chain, e4 2D+bulk, e5 failure+guards) over a shared in-process mock backend (examples/common/mod.rs).
• Tests — 7 HostSession integration tests in src/app/doc_api.rs, incl. roundtrips for 2D entities, geometric methods, and a DWG write→reload roundtrip proving an intersected solid survives with valid ACIS and re-lifts to the expected volume.

Known deviations (documented, not bugs)

• Two geometry_epoch bumps per solid write op (see #7) — host-internal, shared with native commands; monotonic and one-undo-step-per-op are guaranteed.
• extrude/revolve/add_vertex/non-solid transform return ApiError::Unsupported in v1 (profile conversion + per-family transform land in later phases — see IMPLEMENTATION.md).
• volume/centroid are mesh-approximate (render-mesh LOD tolerance), not exact analytic values.