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 HAND-MAINTAINED (src/gen,
│    append-only) → stable discriminants; the spec's op/query names must map to
│    them (asserted by spec_wire_consistency tests).
│
├─ 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`.

## Flow: from the single source of truth to a committed change

The **single source of truth** for the API surface is `spec/entities.toml` —
every entity family, its construction ops, geometric actions, and queries, and
their kernel/acadrust mapping. Everything downstream derives from it. The full
flow from spec to a committed document change:

```mermaid
flowchart TD
    subgraph SRC["Single source of truth"]
        SPEC["spec/entities.toml<br/>families · constructors · methods · kernel map"]
        LAYOUTS["src/gen/layouts.json<br/>Operation/Query wire layouts"]
    end

    subgraph GEN["build.rs codegen (cargo build, CI drift-checked)"]
        OPS["src/gen/ops_gen.rs<br/>Operation enum (append-only)"]
        QRY["src/gen/query_gen.rs<br/>Query enum (append-only)"]
        APIREF["src/gen/api_reference.md"]
        SCHEMA["src/gen/binding_schema.json<br/>(object model + layouts inlined)"]
    end

    subgraph FACADE["Facade (facade.rs) — plugin-facing, object-centric"]
        API["DocApi (root)"]
        DOC["Document (per tab)"]
        COLL["collections: solids() / curves() / entities()"]
        HND["typed handles: Solid · Line · ArcCurve · Text · ...<br/>methods build ops (intersect, transform, create_*)"]
    end

    subgraph WIRE["Wire (envelope/ops/query)"]
        ENV["DocApiEnvelope<br/>Op(Operation) | Queries(Vec)"]
        REC["Receipt: outcome + query_results + new_revision"]
    end

    subgraph TRANS["Transport (the only plugin↔host boundary)"]
        INP["InProcess (host / tests)"]
        IPC["OcsPluginApiIpc (plugin)<br/>PluginRequest::DocApiRequest{tab_id, bytes}"]
    end

    subgraph EXEC["Executor (executor.rs) — crate-owned, one impl"]
        AO["apply_op: validate+compute → push_undo → mutate → finalize_op"]
        AQ["apply_queries: read-only batch (capped)"]
    end

    subgraph HOST["Host backend (src/app/doc_api.rs — HostSession)"]
        BE["DocApiBackend impl<br/>resolve_body · store_solid · transform · add_* · bounds · volume · centroid"]
        TAB["tab auth: reject tab_id ≠ bound tab"]
        SCN["Scene (per tab)<br/>solid_models · meshes · erase_entities<br/>geometry_epoch · doc_api_mass_cache · doc_api_cold_tess_used"]
        CAD["CadDocument (acadrust)<br/>entities · block_records · handles"]
    end

    SPEC -->|spec → enum names + mapping| OPS
    SPEC -->|spec → enum names + mapping| QRY
    SPEC -->|spec → reference| APIREF
    SPEC -->|spec → schema| SCHEMA
    LAYOUTS -->|layouts inlined| SCHEMA

    API --> DOC --> COLL --> HND
    HND -->|method → Operation / Query| ENV
    ENV --> INP
    ENV --> IPC
    INP --> AO
    IPC -->|bincode → host routes DocApiRequest| AO
    AO --> TAB
    AQ --> TAB
    TAB --> BE
    BE --> SCN
    BE --> CAD
    SCN --> REC
    CAD --> REC
    REC -->|deserialized| HND

    classDef truth fill:#1f6feb,stroke:#0b3d91,color:#fff
    classDef gen fill:#2da44e,stroke:#14532d,color:#fff
    classDef hot fill:#bf8700,stroke:#7a5200,color:#fff
    class SPEC,LAYOUTS truth
    class OPS,QRY,APIREF,SCHEMA gen
    class AO,AQ,TAB,SCN hot
```

**How to read it:**

- **Blue (source of truth)** — `spec/entities.toml` + `layouts.json`. Change
  *these* to change the API surface; everything else regenerates or maps onto them.
- **Green (codegen)** — `build.rs` derives the wire enums, the human reference,
  and the binding handover schema. The `Operation`/`Query` enums are the canonical
  append-only wire vocabulary; the spec's `op`/`query` names must map to them
  (enforced by `spec_wire_consistency` tests).
- **Facade → wire → transport** — a plugin's `solid.intersect(&other)` becomes an
  `Operation`, wrapped in a `DocApiEnvelope`, and shipped via the one `Transport`
  (in-process or IPC). Identical request either way.
- **Amber (hot paths)** — the executor's per-op invariant and the host's tab
  authorization + per-tab `Scene` state (solid cache, geometry epoch, the
  persistent cold-tessellation budget). This is where atomicity and the DoS
  boundaries live.
- **Response** — the host produces a `Receipt` (outcome + query results + new
  geometry revision) that the facade turns back into a typed result (`Solid`,
  `Aabb`, `f64`, …).

## 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 `ObjectId`s 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`** are **accuracy-first**: a fine tessellation
  (`mesh_body(0.1, 1e-4)`) for near-analytic results, memoized per
  (handle, geometry_epoch) on the per-tab `Scene`. The cold-tessellation budget
  (256/tab) bounds the DoS surface and **persists across DocApi dispatches**;
  when exhausted the path degrades to the approximate `meshes.metrics` value
  rather than failing.
- **`resolve_body` lift-on-miss** is cheap when the cache is warm (no-op). The
  read-only `with_body` accessor borrows the cache in place (O(1)) instead of
  deep-cloning the B-rep — `bounds()` uses it.
- **IPC** serializes the envelope once; the `bytes` fields use `serde_bytes` so
  the outer frame is a single length-prefixed copy.
- **Tab authorization**: `execute_doc_api` rejects a request whose `tab_id`
  doesn't match the bound tab, so a plugin can't reach tabs it isn't bound to.

---

## 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` accuracy + budget** (was WARNING / perf). They
   re-tessellated the full body (`mesh_body`) + cloned the B-rep per query. Now
   they compute via a **fine tessellation** (`mesh_body(0.1, 1e-4)`) for
   near-analytic accuracy, memoized per (handle, geometry_epoch); the cold-tess
   budget lives on the per-tab `Scene` (persists across dispatches) and degrades
   to the `meshes.metrics` value when exhausted. The duplicated divergence loops
   were merged into one `mesh_volume_centroid` (single source of truth, shared
   by the host + both mock backends).

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.

### Review round 3 — branch review fixes (tab auth, geometry, budget, caps)

A full branch review (all six tracks) found 3 CRITICAL + 5 WARNING + suggestions,
all fixed with regression tests:

1. **Tab authorization (confused deputy)** — `execute_doc_api` ignored `tab_id`,
   so any plugin could reach any open tab. Now rejects `tab_id != host.tab_id()`
   before dispatch (`doc_api_tab_mismatch_is_rejected`).
2. **Negative-bulge arc center mirrored** — `bulge_arc_segment` used signed
   `tan(half)` AND a sign flip, double-counting so CW arcs got the center on the
   wrong side. Now apothem magnitude + sign-picks-side (CW below / CCW above).
3. **Cold-tess budget ineffective** — the 256-tessellation budget lived on
   `HostSession` (rebuilt per dispatch → reset every request). Moved `mass_cache`/
   `cold_tess_used` to the per-tab `Scene` so budget + memoization persist; when
   exhausted it degrades to the approximate `meshes.metrics` value (no hard-fail).
4. **Loft uncapped** — added `BULK_ITEM_CAP` (was the only uncapped multi-item op
   → unbounded kernel call from one request). Regression test.
5. **CreateMany not all-or-nothing** — Curve specs are pre-validated (ellipse ratio)
   in the prepare phase before `push_undo`. Regression test.
6. **Partial-ellipse rotation** — `start`/`end_parameter` now offset by `rot_z`
   (the Arc arm already did). Regression test.
7. **`resolve_body` deep-clone** — added `with_body` borrow accessor; the host
   borrows the cache in place (O(1)) and `bounds()` uses it (no per-query B-rep copy).
8. **`add_raster_image` unvalidated path** — now validates non-empty + image
   extension and rejects UNC/network + parent-traversal paths. Regression test.
9. **Deploy capability gate** — `API_VERSION` 5→6 so DocApi plugins are rejected
   at handshake by old hosts (clean refusal, not a runtime decode error); append-only
   wire + defaulted `doc_api_dispatch` keep older V2–V5 plugins loading unchanged.
10. **Dead code** — `query_name` wired into `apply_queries` error labels; the host
    uses the crate's `ObjectId::from_handle`/`to_handle` (dropped local duplicates);
    deleted `is_null`/`backend_mut`; test mock now stores curve specs + computes
    curve bounds (aligned with the example mock); Spline/Dimension bounds delegate
    to `points_aabb`.

### Known deviations (documented, not bugs)

- **Two `geometry_epoch` bumps per solid write op** (see #7 above) — host-internal,
  shared with native commands; monotonic and one-undo-step-per-op are guaranteed.
- **`volume`/`centroid`** are fine-mesh-approximate (`mesh_body(0.1, 1e-4)`), not
  exact analytic values; the render-mesh `meshes.metrics` is the coarse display LOD.
- **`Angular2Ln` constructor** exists; `Radius`/`Diameter`/`Angular3Pt`/`Linear`
  are the supported dimension sub-types.