Merge pull request #1423 from felixriestra:pr/python-host-model

The bundled `opencad.python` plugin drives OCS through plugin API v7: all
43 canvas entity kinds, the drawing tables, and OCS's own commands run
step by step. RustPython stays in the plugin process — the plugin crate is
outside the workspace with its own lock file, so the application's own
dependencies are unchanged.

Reconciled with the plugin command work that landed as #1425, which the
branch was written before:

- Both added `impl Drop for PluginProcessInteractiveAdapter`, which git
  merges silently into two impls that do not compile. One body now
  cancels the command and then drops it from the runner, in that order: a
  plugin waiting on a step has to be released before the runner forgets
  the command.
- `execute_command` (#1425) and `run_command` (#1423) are both routes from
  a script to the command line, and only the second was guarded. The
  SCRIPTCOMMANDS switch and the denylist are shared now, so neither route
  is the unguarded one.
- `run_command` dispatched with plugin dispatch still enabled, so a script
  naming a plugin command re-entered the plugin that was blocked waiting
  for it. It sets the suppression flag for the length of the dispatch, as
  `execute_command` does.

The denylist read the command as typed, while the dispatcher resolves
aliases: a user-defined `Q` for `QUIT` (ALIASEDIT writes those) walked
past it. It resolves the alias first.

Also: the active-command comparison ran on every message, a mouse move
included, allocating two strings for names that are already `&'static
str`; SCRIPTCOMMANDS' own messages go through the translation macros; and
`docs/.DS_Store` (now ignored) and an unrelated RTF note about constraint
commands are out of the tree.

Co-Authored-By: Claude Opus 5 <[email protected]>

docs/cadcodec-reader-gaps.md

@@ -0,0 +1,220 @@
+# cadcodec DXF reader/writer gaps found by the OCS Python host audit
+
+Reports on `HakanSeven12/cadcodec` (the `acadrust` crate). **Status (21 September
+2026):** fixes for issues 1-6 below, with regression tests, are submitted as
+[HakanSeven12/cadcodec#48](https://github.com/HakanSeven12/cadcodec/pull/48) (branch
+`fix/dxf-reader-writer-roundtrip` on `felixriestra/cadcodec`); the five findings under
+"Observed but not filed" and the style and block ones added later are not filed. Every finding was made against **cadcodec revision
+`5b682ed`** (OCS pins `acadrust` to it) by saving a document with
+`DxfWriter` or `DwgWriter`, reloading it, and comparing entity fields.
+
+Each report names an executable canary in OCS (`src/app/plugin_host.rs`). The
+canaries assert today's wrong result, so they fail loudly once cadcodec is
+fixed; flip the marked expectation when that happens. To reproduce, from the
+OCS repository:
+
+```sh
+STAGE="$PWD/work/bundled-plugins/opencad.python"
+bash plugins/opencad-python/tools/stage-bundled.sh "$STAGE" --debug
+cargo build --bin OpenCADStudio
+OCS_TEST_PYTHON_PLUGIN="$STAGE/libopencad_python.dylib" \
+OCS_PLUGIN_RUNNER_EXE="$PWD/target/debug/OpenCADStudio" \
+cargo test --lib app::plugin_host::tests::<test name> -- --test-threads=1
+```
+
+| # | Area | Severity | Effect |
+|---|---|---|---|
+| 1 | `ATTDEF` reader | high | Most attribute-definition properties silently reset to defaults |
+| 2 | Boolean group codes (290-299) | high | Booleans read through `as_i16()` are never applied |
+| 3 | `UNDERLAY` rotation | high | Rotation is not converted back to radians; repeated saves compound it |
+| 4 | `LEADER` | medium | Annotation link and three vectors are lost |
+| 5 | `DRAWINGVIEW` / `SECTIONLINE` | medium | Typed entity not restored from the ENTITIES section |
+| 6 | `TABLE` merged ranges | low | `merged_ranges` is empty after DXF reopen |
+
+---
+
+## 1. ATTDEF reader handles eight group codes; the writer emits all of them
+
+**Where:** `src/io/dxf/reader/section_reader.rs`, `read_attdef` (around line
+15647). The writer, `write_attdef` in `writer/section_writer.rs` (around line
+4837), emits `7, 11, 41, 51, 70, 71, 72, 73, 74, 210` and `280` in addition to
+the groups the reader consumes.
+
+**What happens:** the reader has arms for groups `1, 2, 3, 10/20/30, 40, 50,
+280` and `101` only; everything else falls through to `_ =>`. After a DXF round
+trip these fields reset to defaults:
+
+- text style name (7)
+- alignment point (11/21/31) and both alignments (72, 74)
+- width factor (41) and oblique angle (51)
+- attribute flags (70): invisible, constant, verify, preset
+- text generation flags (71) and field length (73)
+- normal (210/220/230) and the position-lock state
+
+Tag, prompt, default value, insertion point, height and rotation survive.
+Losing the attribute flags is the worst part: an invisible or constant
+attribute becomes visible and editable after a DXF save.
+
+**Evidence:** `audit_python_attribute_definition_lifecycle_over_real_ipc`
+compares every writable field through both formats. DWG round-trips the full
+state; the DXF digest is pinned to the defaults (see the `BLOCKER` comment on
+`expect_edited_dxf`).
+
+**Suggested fix:** add reader arms for the missing groups, using the same
+conversions the writer applies (rotation and oblique angle are written in
+degrees). `TEXT` and `ATTRIB` already read most of these groups and can share
+the implementation.
+
+## 2. Boolean group codes are read with `as_i16()` and never applied
+
+**Where:** `src/io/dxf/reader/stream_reader.rs` defines
+`DxfCodePair::as_i16()` as `Some` only for `CodePairValue::Int`. Groups 290-299
+are typed `Bool`, so `as_i16()` returns `None` for them and
+`unwrap_or(0) != 0` yields `false`. The pattern appears in many arms of
+`section_reader.rs`.
+
+**Confirmed impact (round-trip tested):**
+
+- `HELIX` group 290 (`handedness`): a clockwise helix reopens counter-clockwise.
+  The reader arm is `290 => { if let Some(v) = pair.as_i16() { ... } }`
+  (around line 12796).
+- `LIGHT` groups 291, 292, 293 (`plot_glyph`, `use_attenuation_limits`,
+  `cast_shadows`; around lines 18154-18182), and 290 for the photometric web
+  file flag: `cast_shadows` reopens `false`.
+
+**Same pattern, not individually tested** (line numbers in `section_reader.rs`):
+13833, 13955-13969 (point-cloud style flags); 18194 (`has_web_file`);
+18431-18438 and 18493-18494 (sweep, loft and revolve option flags); and several
+`if let Some(v) = pair.as_i16()` arms on 290/292 near lines 9815, 10096, 10478
+and 12861. Some other arms already use `as_bool()` correctly (for example lines
+18376 and 18550), so the fix is mechanical.
+
+**Evidence:** `audit_python_helix_lifecycle_over_real_ipc` (canary
+`expect_edited_dxf`) and `audit_python_light_lifecycle_over_real_ipc`.
+
+**Suggested fix:** read these groups with a helper that accepts either
+representation, for example
+`pair.as_bool().or_else(|| pair.as_i16().map(|v| v != 0))`, and audit every arm
+whose code is in 290-299. Alternatively make `as_i16()` accept `Bool` values.
+
+## 3. `UNDERLAY` rotation is written in degrees and read back unconverted
+
+**Where:** `write_underlay` writes group 50 with `underlay.rotation.to_degrees()`
+(around line 11038 of `writer/section_writer.rs`). `read_underlay` stores the
+raw value: `50 => { if let Some(v) = pair.as_double() { underlay.rotation = v; } }`
+(`reader/section_reader.rs`, around line 19470), with no `to_radians()`.
+
+**What happens:** a rotation of `0.5` rad is written as 28.6479 degrees and
+read back as 28.6479 rad. Because the writer converts again on every save, the
+error compounds: a second save-and-reopen yields 1641.4. This silently corrupts
+existing drawings each time they pass through cadcodec.
+
+**Evidence:** `audit_python_underlay_lifecycle_over_real_ipc`; the canary
+`expect_edited_dxf` / `expect_reedited_dxf` records 28.6 then 1641.4.
+
+**Suggested fix:** `underlay.rotation = v.to_radians()` in the reader. Check
+that `DGN`/`DWF`/`PDF` underlays share the code path.
+
+## 4. `LEADER`: annotation link and vectors are lost in DXF
+
+**a. The writer never emits group 340.** `write_leader` writes 3, 71-76, 10, 210,
+211, 212 and 213 but no associated-annotation handle, while the reader has a
+`340 =>` arm that fills `annotation_handle` (around line 16619). A DXF save
+therefore unlinks every leader from its text, tolerance or block annotation.
+
+**b. The coordinate mapping does not reassemble 211, 212 and 213.**
+`GroupCodeValueType::coordinate_axis` in `src/io/dxf/group_code_value.rs` maps
+X to `10..=18 | 110..=112 | 210 | 1010..=1013` (and the Y/Z equivalents), so
+`add_coordinate` ignores the 211/221/231, 212/222/232 and 213/223/233 series.
+`read_leader` uses a `PointReader` for `horizontal_direction`, `block_offset`
+and `annotation_offset`, so all three reopen as their defaults even though the
+writer emits them. (`normal`, group 210, works.)
+
+**c. `override_color` is not persisted** in DXF or DWG: a leader coloured by
+`override_color` reopens `ByLayer`. Observed, cause not traced.
+
+**Evidence:** the canaries in `staged_python_leader_lifecycle_over_real_ipc`
+(search for `BLOCKER`). DWG keeps the annotation link, offset and arrow flag.
+
+**Suggested fix:** write group 340 for a non-null `annotation_handle`; extend
+`coordinate_axis`/`coordinate_group` to cover the 211-213 series (or read those
+groups explicitly); decide where the override colour belongs (group 62/420 on
+the leader).
+
+## 5. `DRAWINGVIEW` and `SECTIONLINE` are dispatched only inside blocks
+
+**Where:** `section_reader.rs` has two entity dispatch tables: one for block
+contents (around lines 3241-3390) and one for the ENTITIES section
+(`read_entities`, from line 3482). `"DRAWINGVIEW"` (line 3386) and
+`"SECTIONLINE"` (line 3382) appear only in the first; the ENTITIES table has no
+arm for them. `write_view_border_dxf` writes `DRAWINGVIEW` correctly.
+
+**What happens:** a `ViewBorder` saved to DXF in the drawing's entity list
+reopens as a different, opaque entity kind instead of `ViewBorder`. DWG restores
+the typed record. The same applies to `SectionSymbol`.
+
+**Evidence:** `audit_python_view_border_lifecycle_over_real_ipc` (canary
+`expect_edited_dxf: "wrong kind"`) and `audit_python_section_symbol_lifecycle_over_real_ipc`
+(canary `wrong kind Unknown`).
+
+**Suggested fix:** add the two arms to the ENTITIES dispatch, calling
+`read_view_border_dxf` and `read_section_symbol_dxf`.
+
+## 6. `TABLE` `merged_ranges` is empty after a DXF reopen
+
+**What happens:** the writer emits the merged-range list (`AcDbFormattedTableData`,
+group 90 then 91-94 per range; near line 10216 of `writer/section_writer.rs`),
+and `reader/section_reader/table_content.rs` (around lines 627-690) appears to
+parse it, yet `Table::merged_ranges` is empty after a DXF reopen. The merge
+itself survives through the origin cell's `merge_width` and `merge_height`
+(groups 175 and 176), and DWG restores `merged_ranges` but not the per-cell
+dimensions.
+
+**Impact:** low, because the merge is preserved in the cell fields; consumers
+that read `merged_ranges` directly see nothing. Cause not traced; it may be that
+the entity path does not call the table-content parser.
+
+**Evidence:** `staged_python_table_lifecycle_over_real_ipc` (the DXF branch
+asserts an empty `merged_ranges` and marks it as a blocker).
+
+**Suggested fix:** rebuild `merged_ranges` from the cell merge dimensions after
+reading, or make sure the `AcDbFormattedTableData` block is parsed for entities.
+
+---
+
+## Observed but not filed
+
+These are format constraints or OCS-side issues, not reader bugs:
+
+- **DWG R2010+ does not store** a leader's `text_height`, `text_width` or
+  `hookline_enabled`, or a 3-D polyline's `elevation`; the writer stores them
+  only for the older versions that define them.
+- **Entity-level `MultiLeader.text_height`** is not stored by either writer
+  (`context.text_height` is), so OCS exposes it read-only.
+- **Legacy `Polyline` reopens as `Polyline3D`** from both formats and a 2-D
+  polyline reopens as `LwPolyline` from DXF. These look like deliberate
+  normalization; OCS made the legacy kind update-only and records the DXF
+  conversion.
+- **Spline weights in DXF** were briefly suspected but are correct: the writer
+  emits group 41 only when `flags.rational` is set, so the host must set that
+  flag when weights are present (fixed in OCS).
+
+### Text and dimension style findings (2026-09-21)
+
+Found by `audit_python_text_and_dim_styles_over_real_ipc`; each is pinned by a canary. The first
+three are fixed in [HakanSeven12/cadcodec#51](https://github.com/HakanSeven12/cadcodec/pull/51)
+(independent of #48); the last two are not filed, because fixing them needs the XDATA layout
+AutoCAD expects and that cannot be checked here.
+
+- **`STYLE` generation flags:** the DXF writer hard-codes group 71 to 0, so a text
+  style's `flags.backward` and `flags.upside_down` are lost on every DXF save (DWG keeps them).
+- **`STYLE` oblique angle units:** group 50 is written and read as the raw radian value, while DXF
+  defines it in degrees; it round-trips inside cadcodec but AutoCAD would read 15 degrees as 0.26.
+  DWG stores radians correctly.
+- **`DIMSTYLE` text style name:** the DXF reader keeps only the text-style handle (group 340) and never
+  resolves `dimtxsty` from it, so the name reopens as `Standard` (the handle is right; DWG resolves both).
+- **`TextStyle::true_type_font`** is never written or read by either codec, so it lives only in memory.
+- **`BLOCK_RECORD` description:** the DXF codec does not carry `BlockRecord::description`
+  (found by `audit_python_blocks_over_real_ipc`, pinned by a canary); DWG keeps it. Not filed, for
+  the same reason as `true_type_font`.
+

docs/cadkernel-body-path.md

@@ -0,0 +1,200 @@
+# Scripting ACIS bodies through cadkernel: findings and plan
+
+Investigation of the blocker on **Solid3D, Body, Region and Surface**
+(`docs/plugin-host-model-coverage-ledger.md`). The blocker said a script can
+neither produce a valid ACIS payload nor edit one, and that the handover
+forbids rewriting an opaque payload without a proven lossless path. This note
+records what OCS's own kernel path can already do, measured with two spike tests
+(`spike_kernel_body_round_trip`, `spike_kernel_timings` in
+`src/app/plugin_host.rs`, both `#[ignore]` because they are slow in a debug
+build). Measured on cadcodec `5b682ed` / cadkernel `6f046af`, debug build.
+
+**Conclusion:** the blocker was overstated. OCS already owns a kernel-backed
+create/transform/boolean pipeline whose output is verified lossless before it is
+accepted. The missing piece is not geometry but an *operation channel* from a
+script to that pipeline. Solid3D and Body are then straightforward; Region and
+Surface need a little more; the one real cost is boolean speed.
+
+## What exists
+
+| Capability | Where | Notes |
+|---|---|---|
+| Primitives: box, wedge, cylinder, cone/frustum, elliptical cylinder, sphere, torus, pyramid, pyramid frustum | `scene/model/solid_model.rs` (`box_solid`, ...) | return a kernel `Body` |
+| Transforms: place, turn about an axis, mirror, column-major 4x4 | `placed`, `turned`, `mirrored`, `by_matrix` | analytic surfaces move with their frames, no point rewriting |
+| Booleans: union, subtract, intersect | `boolean_result` | refuses with a reason instead of returning a broken solid |
+| Body to entity payload | `acis_export::solid_to_sat` | **self-verifying**: it lifts its own SAT text and SAB binary back and returns `None` unless both are lossless (`loss.is_empty()`) and validate |
+| Entity payload to body | `solid3d_tess::kernel_body` / `kernel_region_body` / `kernel_surface_body` / `kernel_acis_body` | returns `None` when the lift is lossy or has more than one body |
+| Regenerating derived data | `app/model_ops.rs::entity_with_boolean_body` | rewrites `acis_data`, `wires`, clears `silhouettes` and `history_handle` for Solid3D, Region and Surface |
+| Volume, extent, edge wires | `volume`, `extent`, `edge_wires` | used as oracles below |
+
+`kernel_acis_body` is exactly the "proven lossless path" the handover asked for:
+a payload is edited only if it lifts with no loss, otherwise it is left alone.
+
+## Spike results
+
+Everything below passed, with the kernel's own volume as the oracle.
+
+| Test | Result |
+|---|---|
+| Box 10x6x4 to Solid3D | volume 240, 12 edge wires, lifts back |
+| DWG save/reopen | lifts back, volume 240, 12 wires kept. `acis_data` changes from SAT text to **SAB binary** (same solid, different bytes) |
+| DXF save/reopen | lifts back, volume 240. Cached `wires` are dropped (0) and are regenerated on demand; silhouettes were already empty |
+| Translate by (5,5,5) | volume 240, extent shifted exactly, lifts back |
+| Rotate 45 degrees about Z | volume 240, extent -5.657..5.657, lifts back |
+| Mirror in X | volume 240, lifts back |
+| Box union cylinder | volume 315.277, 16 wires, lifts back |
+| Box subtract cylinder | volume 189.815, 14 wires, lifts back |
+| Box intersect cylinder | volume 50.185, 2 wires, lifts back |
+| Sphere, torus, wedge, pyramid | volumes 112.696, 98.415, 12.000, 28.532; all lift back |
+| Same payload in a `Body` entity | lifts back; still lifts back after DWG and after DXF |
+
+Timings (debug build): primitive, transform, `solid_to_sat` and `edge_wires` are
+effectively instant (under 0.05 s). **Each boolean took about 23 s**, most likely
+a debug-build artifact for a kernel doing heavy numeric work, but it has not been
+measured in release and must be before booleans are exposed.
+
+Two things to understand about "lossless":
+
+- DWG rewrites SAT text as SAB binary. The solid is identical (same volume,
+  topology, faces) but the bytes are not, so the honest oracle is "lifts back with
+  no loss and the same volume", not byte equality. An untouched body that a
+  script never edits is written exactly as OCS writes any other body.
+- DXF does not carry the cached wires; they are derived data.
+
+## Design
+
+The obstacle is the channel. The generic entity path moves an acadrust
+`EntityType` from the plugin to the host; the plugin has no kernel and must never
+see or rewrite ACIS bytes. Three ways to give a script the operations:
+
+**A. Host-side normalization with a request carrier (no ABI change).** A
+hand-written converter (as for Dimension) turns `create_entity('Solid3D',
+primitive='box', ...)` into a Solid3D that carries the request in an otherwise
+unused field, and the host's `normalize_scripted_entity` replaces it with the real
+payload, exactly as it already does for MLine geometry, Helix splines and image
+definitions. It works inside today's v7 protocol, but the carrier field is a hack.
+
+**B. New host operation (recommended).** Add one additive operation to `HostApi`
+and the v4 IPC protocol, for example `solid_operation(op) -> Result<Handle, String>`,
+with `op` one of: create primitive, transform, boolean, and (later) region from
+curves. The host runs it through the pipeline above inside an undo step and
+returns the new or updated handle. Because it is a new method with a default
+"unsupported" implementation it is backward compatible; bump the minor/negotiate
+by capability rather than the major version. Python side:
+
+```python
+box  = doc.solids.box(center=(0, 0, 0), size=(10, 6, 4))
+cyl  = doc.solids.cylinder(base=(0, 0, -3), radius=2, height=10)
+hole = box.subtract(cyl)            # new Solid3D; operands untouched
+box.transform(translate=(5, 5, 5))  # in-place, transactional, undoable
+```
+
+**C. Do nothing but layer edits** (the current state).
+
+Recommended: **B**, with `solid_operation` covering create, transform and boolean.
+Every operation goes through `solid_to_sat` (self-verifying) and the kernel's own
+refusal path, so a failure is an error before any mutation, and an untouched
+payload is never rewritten. In-place edits of an existing entity are gated by
+`kernel_acis_body` returning `Some`: a payload the kernel cannot lift losslessly
+is refused with a clear message instead of being rewritten.
+
+## Per-kind feasibility
+
+| Kind | Create | Edit | Notes |
+|---|---|---|---|
+| **Solid3D** | 9 primitives, boolean of two solids | transform, boolean | Straightforward. Regenerate `wires`; clear `silhouettes`; `history_handle` is cleared by `entity_with_boolean_body`, so a history-carrying solid needs a decision (refuse, or accept losing parametric history). |
+| **Body** | same payload container | transform | Same pipeline, `kernel_acis_body` works on a `Body` payload (spike). A true non-solid (sheet or wire) body may not lift; those stay layer-only. |
+| **Region** | from closed curve entities (the REGION command's `add_region_model`) | transform | Needs a "region from these curve handles" operation and planar-face construction. |
+| **Surface** | plane, extruded, revolved from a profile | transform | The most involved: surface kinds carry `surface_data` besides `acis_data`, and only `Plane` keeps its kind on regeneration (`SurfaceKind::Generic` otherwise). |
+
+## Risks and open questions
+
+1. **Boolean speed.** Measured in release, see "Boolean timings" below: about
+   1 to 2.2 s for a box and a cylinder, 0.2 s for two spheres and 1 to 2 ms for
+   planar-only operands, against 23 s in a debug build. The kernel also refuses
+   many curved cases, which matters more than speed.
+2. **Interoperability cannot be verified here.** `solid_to_sat` is verified by
+   OCS's own lifter. Whether AutoCAD accepts the SAT/SAB that OCS writes is not
+   testable without AutoCAD, so completion should be scoped as "OCS round trip",
+   as for RasterImage.
+3. **Parametric history.** Regenerating a payload clears `history_handle`.
+4. **Frames.** Some solids carry a body-to-world transform in the SAT
+   (`body_transform` in `kernel_acis_body`); the lift already applies it, and the
+   spike's translated/rotated bodies confirm it, but a foreign DWG with a
+   scaled or sheared body transform should be added as a fixture.
+5. **API surface.** `solid_operation` is a protocol addition; decide whether it is
+   one generic operation enum or separate methods before starting.
+
+## Suggested phases
+
+1. `solid_operation` protocol and host executor for **create primitive** and
+   **transform** on Solid3D, with the full lifecycle test through the real runner
+   (volume oracle, DWG and DXF reopen, undo, refusal of a lossy payload).
+2. **Booleans** (after release-build timing) and the **Body** container.
+3. **Region** from curve handles.
+4. **Surface** (plane first).
+
+Phase 1 alone would move Solid3D from blocked to complete-in-OCS.
+
+**Status (2026-09-20): phase 1 is done.** `HostApi::solid_operation` (create primitive and rigid transform), the `doc.solids` Python API and `audit_python_solid3d_lifecycle_over_real_ipc` are in; Solid3D is complete, Body moves through the same channel. Design B was implemented as recommended. Region creation from a closed profile followed (`RegionFromProfile`). Plane surfaces and extrusions (`SurfaceFromProfile`, `Extrude`) followed. Only booleans remain, plus lofted, revolved, swept and NURBS surfaces.
+
+## Boolean timings (release build)
+
+Measured 2026-09-20 in a scratch crate built with `--release` (opt-level 3)
+against the same cadkernel revision OCS pins (`6f046af`, features `acis` and
+`offset`), calling exactly what OCS's `solid_model::boolean_result` calls:
+`brep::operation_tolerance` then `brep::combine`. A debug build of OCS is about
+22 times slower, so booleans must never be exercised in a debug test run. The
+scratch program is not in the repository; to repeat it, depend on cadkernel at
+that revision and time `brep::combine` on `brep::make::{cuboid, cylinder,
+sphere, torus}` operands.
+
+| Operation | Time | Result |
+|---|---|---|
+| box union / subtract / intersect cylinder (10x6x4 box, r=2 cylinder) | 1.05 to 1.08 s each, identical on repeat runs | ok |
+| same, operands scaled 10x and 100x | 2.21 s and 2.21 s | ok |
+| box union / subtract box (planar only) | 0.001 to 0.002 s | ok |
+| sphere union sphere (overlapping) | 0.22 s | ok |
+| sphere subtract sphere (overlapping) | 0.23 s | refused `CutRefused` |
+| box subtract sphere (sphere cutting the box faces) | 1.28 s | refused `Coincident` |
+| sphere union torus (disjoint) | under 1 ms | refused `NoClosedForm` |
+| torus subtract cylinder through the ring | under 1 ms | refused `NoClosedForm` |
+| drill a first cylinder hole in a box | 0.03 s | ok |
+| drill a second hole in the drilled box | under 1 ms | refused `CutRefused` |
+
+What this means:
+
+- **Speed is acceptable.** A curved boolean costs 0.2 to 2.2 s, the same cost as
+  the GUI BOOLEAN command, and planar work is instant. The 23 s seen earlier was
+  a debug-build artifact.
+- **It blocks the host thread.** The plugin's `PY_RUN` is a synchronous dispatch
+  and nested host requests run inline, so a script freezes the UI while a
+  boolean runs. One to two seconds per operation is tolerable; a script with
+  dozens is not.
+- **The whole script has a budget.** A `Dispatch` call uses the 30 s default
+  timeout (`OCS_PLUGIN_CALL_TIMEOUT_SECS`, with a 10 s floor), and nested host
+  work counts against one deadline. Roughly fifteen curved booleans in a single
+  script would exceed it.
+- **Refusals are the real limit.** The kernel says no often: coincident faces, a
+  cut it has no closed form for, torus operands, and, surprisingly, a second
+  cut in a body that was already drilled. Refusals are fast and leave the inputs
+  intact, which is the behavior the API already relies on, but it means booleans
+  will be a partial feature that fails with a reason, not a general one.
+- **Timing is not proportional to size.** Scaling the operands 10x doubled the
+  time, 100x changed nothing more, so the cost is dominated by the surface
+  intersection setup rather than the geometry size.
+
+### Recommendation
+
+Add `SolidOperation::Boolean { first, second, operation, layer }` and run it
+synchronously on the host thread, surfacing the kernel's refusal (`Coincident`,
+`CutRefused`, `NoClosedForm`, ...) verbatim in the error and leaving both
+operands untouched on failure. Build the result with the existing
+`entity_with_boolean_body` path so it inherits the lossless verification.
+Test it with **planar** operands (millisecond cost, safe in debug) plus one
+`#[ignore]` curved case that documents the release-only runtime. Document the
+30 s script budget and that chained cuts on a drilled body are often refused.
+Do not move booleans to a background thread yet: it would need cancellation and
+undo coordination for a cost that is one to two seconds.
+
+**Status (2026-09-20): implemented.** `SolidOperation::Boolean` and `doc.solids.union`, `subtract` and `intersect` follow the recommendation above, with planar-operand lifecycle testing and an ignored curved refusal test. Every operation this note proposed is now built.

docs/plugin-architecture.md

@@ -9,12 +9,12 @@ with Open CAD Studio. The model follows [QGIS](https://plugins.qgis.org/)-style
 extensibility: a small metadata file, a single entry point, an optional separate
 engine crate, and user-installable packages from a curated index.
 
-> **Open CAD Studio ships no built-in plugins.** Every add-on is an **external
-> dynamic library** (`cdylib`) the host loads at runtime from the user plugins
-> folder. The host source only contains the generic plugin *runtime*
+> Plugins are **out-of-process dynamic libraries** (`cdylib`). The host loads
+> first-party packages from its application resources and third-party packages
+> from the user plugins folder. Both use the generic runtime
 > (`src/plugin/`, `src/app/plugin_host.rs`) and the stable contract crate
-> (`crates/ocs_plugin_api`). Add-ons live in their own repositories and
-> **consume** that contract.
+> (`crates/ocs_plugin_api`). A user package with the same id explicitly
+> overrides a bundled package.
 
 ---
 
@@ -24,7 +24,7 @@ engine crate, and user-installable packages from a curated index.
 |------|-----------|
 | **One package, one entry point** | Manifest, ribbon tab and commands ship together in the plugin crate; no edits to the host. |
 | **Stable contract** | Authors target the semver-versioned `ocs_plugin_api` crate, not `OpenCADStudio` internals. |
-| **Out-of-tree by default** | A plugin is its own repo + crate; the host never recompiles to gain one. |
+| **Out-of-tree by default** | Third-party plugins remain independent; selected first-party plugins may build and ship with OCS. |
 | **DWG round-trip** | Domain data lives on entities as XDATA, not in an opaque side database. |
 | **Engine reuse** | A headless `std`-only engine crate can run in WASM/CLI without the CAD host. |
 

docs/plugin-host-model-completion-plan.md

@@ -0,0 +1,341 @@
+# OCS canvas entity completion plan
+
+## Goal and current state
+
+Build a general Python document model over the OCS host API so a script can control OCS: read and change every canvas entity, manage the drawing's tables, and run OCS's own commands. Keep a property-level record of read/write, read-only, snapshot-only, and unsupported fields in the [43-kind coverage ledger](plugin-host-model-coverage-ledger.md). The architecture and guarantees are in [plugin-host-model.md](plugin-host-model.md); the progress log at the end of this file records each increment with its evidence. Do not resume the separate Lisp-to-Python conversion work.
+
+**State as of 21 September 2026.** The feature is host API v7. An earlier draft pull request, [#1391](https://github.com/HakanSeven12/OpenCADStudio/pull/1391), covered the first slice of it and was closed in favour of this more complete change.
+
+- **Entities:** explicit writes for all 43 canvas kinds (41 creatable; the legacy `Polyline` and `Body` are update-only). **31 kinds are `Complete`** (every C/R/E/D/U/I/W/V/P gate passes). The remaining kinds are integration-tested and held short of `Complete` by a named blocker in the ledger: seven by cadcodec DXF bugs (fixes submitted as [cadcodec#48](https://github.com/HakanSeven12/cadcodec/pull/48), not yet merged, so OCS still pins the unfixed revision), Polyline3D by the DWG format, Polyline2D by a kind change on DXF save, RasterImage by an image-reactor structure that cannot be verified, and Body by having no creation path.
+- **Drawing tables:** layers, text and dimension styles, blocks and their contents, linetypes and layouts, through the additive `TableOperation` request (see the log entries dated 2026-09-21).
+- **Commands:** `HostApi::run_command` drives the real OCS commands step by step; `doc.command`, `doc.start_command` and `doc.modify` build on it.
+- **Known open items:** the unfiled cadcodec findings (`cadcodec-reader-gaps.md`), complex (text and shape) linetypes, plot devices and named page setups, and PEDIT's remaining options.
+
+Repositories:
+
+- Bundled Python adapter: `plugins/opencad-python`
+- Host coverage policy: `crates/ocs_plugin_api/entity_coverage_policy.json`
+- Host coverage/validation: `crates/ocs_plugin_api/src/entity_coverage.rs` and `build.rs`
+- Adapter mapping: `plugins/opencad-python/entity_manifest.json`,
+  `plugins/opencad-python/build/generate.rs`,
+  `plugins/opencad-python/src/ocs_module.rs`, and
+  `plugins/opencad-python/src/document_model.py`
+- Host design notes: `docs/plugin-host-model.md`
+
+Host and adapter changes live in the same repository and are committed together.
+
+## First: complete the originally agreed Phase 8
+
+The earlier Phase 8 was **integration and compatibility**, not a new entity kind. `Insert` was added afterward as a separate coverage increment. Before marking any kind complete, establish an executable integration harness that exercises the actual plugin runner and IPC, not only direct Rust conversion helpers:
+
+1. Stage the in-tree v7 plugin with `bash plugins/opencad-python/tools/stage-bundled.sh <stage directory> [--debug]`. Verify the staged `plugin.toml` says API v7 and its acadrust source and Rust compiler match OCS. Keep the repository-relative `ocs_plugin_api` path; never check in a machine-local path.
+2. Through real IPC, create, inspect, edit, and delete a representative entity. Verify an invalid multi-entity transaction changes nothing, a valid transaction produces one undo entry, and undo **and redo** restore the expected geometry and references.
+3. In the running GUI, exercise a real point pick, entity pick, cancellation/Escape, and plugin command cancellation. Verify drawing/selection/command notifications, including overflow recovery.
+4. Repeat an input request and event poll across two tabs; verify token and notification isolation and cleanup when a tab closes.
+5. Save and reopen representative edits as **DWG and DXF**, verifying the actual geometry and preserved unmapped fields. Use a real viewport/canvas check where the entity has visible geometry; a converter round trip alone does not satisfy this.
+6. Record platform, OCS/acadrust revisions, fixture files, commands, results, and any engine limitation. Keep repeatable tests in the relevant repositories.
+
+Phase 8 is complete only when these checks pass through the bundled plugin and
+real runner boundary. If a test is blocked by OCS or acadrust behavior, record
+the specific failure and leave Phase 8 open.
+
+## Per-kind completion gate
+
+Use one checklist row per kind in a coverage ledger. Status values: `unstarted`, `mapped`, `integration-tested`, `complete`, or `blocked`; record the blocking dependency. **Do not use “complete” for read-only, update-only, or layer-only support.** For every kind:
+
+1. **Declare coverage:** Every traced field has an accurate catalog status and validation rule. Distinguish ordinary properties from handles, owners, linked records, external assets, and opaque payloads. Snapshot-only fields remain explicitly unmapped. Assert adapter keys match the host catalog.
+2. **Create:** A Python script creates a valid entity through the document model in a real document with required tables, styles, definitions, files, and references. Missing or invalid required inputs fail before mutation. Add document-model creation/deletion methods if needed; current `doc.entities` only indexes and iterates, while low-level `ocs.add`/remove APIs exist.
+3. **Read and edit:** After creation, read the entity by handle through `doc.entities`; edit at least one defining geometry or placement field and one other meaningful writable field inside `doc.transaction`. Verify that all unmentioned fields, handles, ownership, attached records, and XDATA remain unchanged. Check invalid values and forbidden reference edits fail atomically.
+4. **Delete and history:** Delete the created entity through the Python interface. Prove create, edit, and delete have defined undo/redo behavior in the host, including grouped writes and failure rollback. Record any transaction API extension and bump the host API version if its ABI changes; keep older plugin compatibility.
+5. **Real IPC and canvas:** Run the above through the staged plugin and actual OCS IPC. Verify visibility/geometry in the canvas and selection or picking in the GUI. For nonvisual entities, verify their observable document or layout behavior and explain the oracle.
+6. **Persistence:** Save/reopen DWG **and** DXF fixtures. Compare kind, geometry, important metadata, handles/references, and preserved fields after reopen; edit again after reopen. Test at least one valid edge case for that kind. Do not count a JSON or in-memory round trip as file persistence.
+7. **Packaged build:** Run the in-tree adapter tests with `--locked`, stage the
+   plugin with `stage-bundled.sh`, and load it from the macOS application
+   resources through the separate runner process. The staged manifest must
+   match the host's Rust compiler and acadrust source.
+
+If OCS/acadrust cannot create or serialize a kind reliably, mark it **blocked**, add a regression test or fixture demonstrating the failure, and move to the next independent kind. An explicit unsupported status is honest progress, not completion.
+
+## Existing mapped kinds: audit before claiming completion
+
+Audit these against the same gate: `Point`, `Line`, `Circle`, `Arc`, `Ellipse`, `Polyline`, `Polyline2D`, `Polyline3D`, `LwPolyline`, `Spline`, `Text`, `MText`, `Ray`, `XLine`, `Solid`, `Face3D`, `Insert`. `Insert` currently has transform edits but **no Python creation**; its block name is read-only and attached attributes are snapshot-only. Earlier tests include some direct DWG round trips, but there is no evidence that every mapped kind passes real IPC, GUI, deletion, undo/redo, and both file formats. Mark each independently after testing.
+
+## Ordered 26-kind expansion queue
+
+The order below groups shared implementation work. Complete a kind only through the gate above. Within a group, move past a blocked kind after recording the exact dependency. “Minimum exercise” identifies a real entity-specific create/edit/delete case; it does not make other fields automatically writable.
+
+| # | Kind | Minimum entity-specific exercise and dependency |
+|---:|---|---|
+| 1 | Tolerance | Create a feature-control frame with text/style; move and edit its text/direction; check style reference and display. |
+| 2 | Shape | Create with an installed SHX shape/style; change insertion, size, rotation; verify the named glyph and style survive reopen. |
+| 3 | AttributeDefinition | Create in a block definition; edit tag, default text, and placement; verify the block’s definition and linked inserts. |
+| 4 | AttributeEntity | Create as a block reference attribute; edit value and placement; verify parent `Insert`, handles, and sequence linkage. |
+| 5 | Hatch | Create a closed-boundary solid hatch and a patterned hatch; edit boundary/pattern; verify fill and boundary validity. |
+| 6 | Leader | Create with vertices and an annotation; edit path and annotation placement; preserve annotation handle. |
+| 7 | MLine | Create against a valid MLine style; edit vertices and scale; verify style element offsets and joins. |
+| 8 | Dimension | Create at least one supported dimension subtype with style and reference points; edit defining geometry and displayed measurement. Track subtype coverage separately. |
+| 9 | MultiLeader | Create text and leader paths using a valid style; edit landing/vertices and text; preserve nested context and annotation links. |
+| 10 | Table | Create rows, columns, style, and cells; edit size and one cell value; preserve merged ranges and block/style links. |
+| 11 | PolygonMesh | Create a grid with defined M/N counts and vertices; edit a vertex and density; reject inconsistent counts. |
+| 12 | PolyfaceMesh | Create vertices/faces; edit a vertex and face indices; reject invalid indices and preserve sequence records. |
+| 13 | Mesh | Create vertices/faces/edges; edit one vertex and topology; reject out-of-range indices and verify rendered faces. |
+| 14 | Helix | Create with axis, radius, turns, and height; edit a defining parameter and verify the derived curve plus embedded spline data. |
+| 15 | RasterImage | Create with a resolvable image definition/file; edit placement, vectors, and clipping; verify display and definition handles. |
+| 16 | Wipeout | Create with a valid clip polygon; edit boundary and placement; verify masking, clip mode, and image-definition links. |
+| 17 | Underlay | Create with a valid PDF/DWF/DGN definition; edit transform and clipping; verify external resource and definition handle. |
+| 18 | Viewport | Create in the appropriate layout; edit center/size/view target; verify visible viewport and frozen-layer/clip references. |
+| 19 | ViewBorder | Create with its required view/scale references; edit border geometry; verify linked viewport/view records. |
+| 20 | SectionSymbol | Create with view style and point records; edit endpoints/label; preserve view-representation links. |
+| 21 | Light | Create a light with position/target; edit intensity and direction; verify color/photometric state and visible glyph. |
+| 22 | Region | Create/import a valid region payload; transform/edit supported geometry, then verify ACIS payload after both file formats. |
+| 23 | Body | Create/import a valid body payload; apply a supported transform/edit; verify ACIS and history/reference preservation. |
+| 24 | Solid3D | Create/import a valid solid; edit a supported geometric operation; verify ACIS, topology, and history after reopen. |
+| 25 | Surface | Create/import a valid surface; edit a supported parameter/transform; verify surface payload, isolines, and history. |
+| 26 | Ole2Frame | Create with a valid embedded object payload; edit frame geometry; verify storage, aspect behavior, and persistence. |
+
+The last five may require new engine capabilities rather than only Python converters. Do not deserialize and rewrite their opaque payloads unless lossless behavior is proven. If a listed kind has no meaningful safe Python creation/edit path, keep it marked blocked or partial and report why; do not relabel it complete to reach 43/43.
+
+## Work pattern for each coding increment
+
+1. Inspect the acadrust entity struct, constructors, private fields, serializer, drawing path, and linked tables/objects. Record the intended editable/read-only/unmapped properties first.
+2. Put generic validation and transaction behavior in the host. Keep the Python adapter thin; add a manifest override only when the generator cannot safely express a field.
+3. Add focused host validation, adapter conversion, document-model, real transaction/undo/redo, IPC, GUI, and DWG/DXF fixture checks. Record test evidence in the ledger, including which checks were manual.
+4. Run `cargo test -p ocs_plugin_api --features host --lib` and the relevant
+   app host tests. Run
+   `cargo test --locked --features experimental-host-model --manifest-path plugins/opencad-python/Cargo.toml`
+   plus
+   `python3 -m unittest discover -s plugins/opencad-python/tests -v`.
+5. Check `git diff --check` and repository status, commit host and adapter changes
+   together, and record the resulting commit and the next unfinished gate in the ledger.
+
+## Phase 8 progress log
+
+- Added a V4 local-socket nested-request test for `UpdateEntitiesTransaction` using a simulated runner peer and a recording host. This proves the request and response cross the V4 IPC framing and reach `HostApi`; it does **not** prove the actual Python plugin runs through IPC.
+- Extended the OCS app-host Point batch test to assert redo after undo. This proves the real app history path for those edits; creation/deletion history remains untested by this case.
+- Staged the actual debug Python cdylib with `stage-bundled.sh`. Its generated
+  manifest declares API v7 and the exact OCS acadrust and Rust compiler
+  fingerprints. The plugin now builds from `plugins/opencad-python` in this
+  repository and ships from the macOS application resources.
+- The opt-in `staged_python_plugin_line_lifecycle_over_real_ipc` app test passed with the staged v7 Python plugin and built OCS executable. It creates, edits, and deletes a Line through Python over the actual runner IPC; confirms three undo entries and undo/redo; and writes/reopens the edited Line as DWG and DXF. It does not exercise GUI picking, multiple tabs, or cancellation. Re-run with `OCS_TEST_PYTHON_PLUGIN=<staged dylib> OCS_PLUGIN_RUNNER_EXE=<built OpenCADStudio executable> cargo test app::plugin_host::tests::staged_python_plugin_line_lifecycle_over_real_ipc --lib -- --test-threads=1 --nocapture` from the OCS checkout.
+- The same Line test now also sends a duplicate-handle batch through Python and confirms the host rejects it without changing geometry or creating an undo entry.
+- The opt-in `staged_python_point_pick_and_cancel_over_real_ipc` test passes with the same runner. It requests point and entity picks through Python, drives the app's active-command point/object-pick callbacks, polls the returned tokens through a later Python run, and verifies Enter cancellation. The callbacks are invoked by the test harness, not by a physical GUI pointer event; live GUI verification remains open.
+- The opt-in `staged_python_tabs_isolate_tokens_and_notifications` test passes with two real OCS document tabs and the staged runner. A token created in tab 0 cannot be observed or consumed in tab 1 before or after completion. Host-to-plugin DrawingChanged notifications for both tab ids are delivered over IPC and drained only by their owning tab. A 257-event burst reports overflow, and `DocumentTabClosed` discards queued events for that tab.
+- Added `doc.create_entity(kind, **properties)` and `doc.delete_entity(entity_or_handle)` to the high-level Python document model. Unit tests cover forwarding and managed identity fields. The real staged-plugin Line lifecycle now uses these methods rather than low-level `ocs.add`/`remove_entity`.
+- Closed the first new-kind increment for `Tolerance`. The host coverage catalog now maps insertion point, direction, normal, text, dimension style name, text height, and gap; validates geometry and document style references; keeps the style handle read-only; and leaves the undocumented DWG short unmapped. The thin adapter adds generated conversion plus stale style-handle clearing when the style name changes.
+- `staged_python_tolerance_lifecycle_over_real_ipc` passes the full C/R/E/D/U/I/W/V/P gate with the actual runner: high-level create/read/transaction edit/delete, live canvas selection, undo/redo, invalid direction and missing style rollback, untouched-field preservation, and DWG/DXF reopen. Tolerance is recorded as **Complete** in the ledger. The queue now continues with `Shape`.
+- Closed `Shape` with a generated SHX fixture and a real shape-file `TextStyle`. Host-owned binding resolves the Python style name to the stable table handle required by DWG; validation rejects missing/non-shape styles and invalid geometry. The adapter maps all stable shape fields and keeps the bound style handle read-only.
+- `staged_python_shape_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P through the actual runner, checks the real SHX linework before and after DWG/DXF reopen, and proves that invalid size/style edits remain atomic. The DXF renderer fallback now searches named `is_shape_file` styles as well as legacy unnamed styles. Shape is **Complete**; the queue now continues with `AttributeDefinition`.
+- Added creation-time `owner_handle` to the generated document-model adapter. It is present in snapshots and accepted by `doc.create_entity`, but rejected after creation; host transactions independently reject owner changes. Generic host validation now requires a non-null canvas owner to resolve to a block record, except `AttributeEntity`, whose owner may be an `Insert`.
+- Mapped stable AttributeDefinition fields and validated tag, placement, normal, height, width, angles, text style, line count and block ownership. `embedded_mtext` stays snapshot-readable but unmapped so partial Python edits preserve its linked R2018+ layout payload.
+- `staged_python_attribute_definition_lifecycle_over_real_ipc` passes the real create/read/edit/delete/undo/selection/render/validation/packaged-build path using a structurally valid block and linked Insert. Full DWG state and core DXF geometry survive reopen; deletion stays absent after both formats. OCS also stopped double-converting ATTDEF/ATTRIB DXF rotation already converted by acadrust.
+- AttributeDefinition remains **Integration-tested / DXF blocked**, not Complete: acadrust `568a12c`'s ATTDEF DXF reader did not restore optional AcDbText fields including width factor. Revalidate this recorded failure against the currently merged `7ea4247` revision before keeping or clearing the W-gate blocker.
+- Closed `AttributeEntity` without flattening canonical drawing storage. V4 views and IPC snapshots expose each nested child by handle, while host create/update/delete and transactions rewrite the owning Insert so rendering, serialization and undo remain consistent.
+- `staged_python_attribute_entity_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P with the actual v7 adapter. It creates a linked attribute from its block's ATTDEF, reads and edits value/placement/rotation, selects the parent Insert, renders text, rejects invalid tag/height/owner edits atomically, reopens edited and deleted state in DWG and DXF, and proves three-step undo/redo. AttributeEntity is **Complete**; the queue now continues with `Hatch`.
+- Completed `Hatch` with full solid/pattern definitions and typed nested boundary paths. The adapter generator now handles single-payload tagged enums as `{kind, value}` dictionaries, which covers every Hatch edge variant and is reusable by later nested entity models. Unknown adapter properties are rejected instead of being silently ignored.
+- `staged_python_hatch_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P with closed line-loop fixtures: solid creation, conversion to a stored-line pattern, boundary replacement, selection and live render-cache checks, atomic invalid scale/association/open-loop/unmapped-payload rejection, edited/deleted DWG and DXF reopen, post-reopen edits, and three-step undo/redo. Hatch is **Complete**; the queue now continues with `Leader`.
+- Mapped `Leader` (host validation and reference binding in `entity_coverage.rs`, policy/build.rs/manifest entries, adapter count 23). `staged_python_leader_lifecycle_over_real_ipc` passes C/R/E/D/U/I/V/P through the real runner. W is blocked by acadrust: the DXF writer omits the annotation handle (340), DXF reads lose `annotation_offset` (213), and DWG R2010+ does not store text size or hookline flag. Each gap is pinned by a canary assertion so it fails loudly once fixed. The queue now continues with `MLine`.
+- Completed `MLine`. Host validation and style binding live in `ocs_plugin_api`; derived vertex geometry and element parameters are recomputed by the host (`normalize_scripted_mline`) on scripted create/edit, so scripts supply positions only. The adapter maps `flags` as an integer through a manifest override because the generator cannot classify acadrust's serde-newtype `MLineFlags`. `staged_python_mline_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P with DWG and DXF reopen. The queue now continues with `Dimension`.
+- Completed `Dimension` for all nine subtypes. Because the payload is an enum, the adapter generator gained a `manual_kinds` hook (hand-written `<kind>_to_dict/_from_dict/_apply`) and the host catalog a `synthetic` policy section. The host derives `actual_measurement` and the base definition point on every scripted create/edit. Python ints are now accepted wherever a coordinate or angle is expected. `staged_python_dimension_lifecycle_over_real_ipc` records each subtype separately and all nine pass C/R/E/D/U/I/W/V/P. The queue now continues with `MultiLeader`.
+- Completed `MultiLeader`. The adapter generator now converts `Color`, `LineWeight`, mixed unit/payload enums, fixed float arrays and bitflags-2 newtypes, and a `keep_types` override lets a hand-written setter reuse generated converters (used for the merge-style `context` patch). `Leader.override_color` became writable through the same `Color` form; neither file format stores it. `staged_python_multileader_lifecycle_over_real_ipc` passes the full gate with DWG and DXF reopen. The queue now continues with `Table`.
+- Completed `Table`. The generator now handles tuples and `usize`; the host keeps DXF cell merge dimensions in step with `merged_ranges`. `staged_python_table_lifecycle_over_real_ipc` passes the full gate with DWG and DXF reopen. The queue now continues with `PolygonMesh`.
+- Completed `PolygonMesh`, `PolyfaceMesh` and `Mesh` (queue items 6-8) with one shared `run_mesh_lifecycle` test driver and per-kind host validation. The generator now omits a sub-record's own `EntityCommon` from the scripted form. All three pass the full gate including DWG and DXF reopen with re-edit. The queue now continues with `Helix`.
+- Mapped `Helix` with a host-rebuilt spline. `run_mesh_lifecycle` gained per-format DXF expectations so an engine gap is pinned by a canary instead of hidden. All gates pass except W for `handedness` in DXF (reader ignores boolean group 290). The queue now continues with `RasterImage`.
+- Mapped `RasterImage`. The host reads the image file, creates and links the `ImageDefinition`, and derives `size` and the default clip boundary. The shared lifecycle driver passes every gate in OCS with a real PNG; `ACAD_IMAGE_DICT`/reactor creation is not implemented, so the kind stays integration-tested. The queue now continues with `Wipeout`.
+- Completed `Wipeout` (queue item 11) with rectangular and polygonal clip masks through the shared lifecycle driver; scripted creation matches OCS's native command. The queue now continues with `Underlay`.
+- Mapped `Underlay` against a fixture PDF `UnderlayDefinition`. All gates pass except DXF W: the reader does not convert the degree-valued rotation back to radians, and repeated DXF round trips compound the error (pinned by a canary). The queue now continues with `Viewport`.
+- Mapped `Viewport` with a paper-space owner rule and frozen-layer reference validation. Every gate except a paper-space canvas oracle passes through the shared driver; the kind stays integration-tested. The queue now continues with `ViewBorder`.
+- Mapped `ViewBorder` with viewport and scale reference rules. All gates pass in DWG; DXF loading does not restore the typed entity (pinned by a canary). The queue now continues with `SectionSymbol`.
+- Recorded `SectionSymbol` (queue item 15) as **blocked**: it needs a section view style and view representation the host cannot create, and its raw point-count fields have no documented derivation. Mapped `Light` (item 16); every gate passes except DXF `cast_shadows`, which the reader drops (pinned by a canary). The queue now continues with `Region`.
+- Recorded `Region`, `Body`, `Solid3D`, `Surface` (queue items 17-20) and `Ole2Frame` (item 21) as **blocked**. The ACIS kinds need a host-side kernel-backed create/transform API that regenerates the payload, wires and silhouettes; the OLE frame needs a valid embedded-storage fixture. No opaque payload is rewritten. With this the ordered queue is complete: 12 kinds are fully complete, Leader, Helix, Underlay, ViewBorder and Light are mapped but blocked at DWG/DXF persistence by acadrust gaps, RasterImage and Viewport lack an oracle or linkage, and six kinds are blocked. Next work is the engine fixes behind the canary assertions, the mapped-kind audit of the 17 pre-existing kinds, and merging `origin/main`.
+- Audited the 17 pre-existing mapped kinds through the shared real-runner driver (`audit_python_*`). The audit found and fixed genuine validation gaps: Ellipse had none, Text and MText accepted a zero height, Arc accepted non-finite angles, Point and Line accepted infinite thickness, and most basic kinds had no creation-time validation. A shared `validate_basic_entity` now covers Point, Line, Circle, Arc, Ellipse, Text, MText, LwPolyline, Polyline, Polyline2D, Polyline3D and Spline, refusing only problems an edit introduces so already-invalid legacy values stay editable. Twelve of the 17 kinds now pass every gate (Point, Line, Circle, Arc, Ellipse, LwPolyline, Text, MText, Ray, XLine, Solid, Face3D). Four expose persistence findings pinned by canaries (Polyline reopens as Polyline3D; Polyline2D reopens as LwPolyline in DXF; Polyline3D loses elevation in DWG; Spline loses weights in DXF), and Insert is update-only with all applicable gates passing. The driver gained per-format DWG expectations and a host-made block fixture for Insert.
+- Audited `AttributeDefinition` against acadrust `5b682ed` with a full-field comparison through both formats. Everything passes in DWG. DXF keeps only tag, prompt, value, insertion point, height and rotation because the reader handles eight group codes; alignment, width factor, oblique angle, attribute flags, field length, generation flags, lock and text style reopen as defaults. The kind stays integration-tested and the gap is pinned by canary expectations; the fix belongs in cadcodec's `read_attdef`. The shared driver's block fixture now also serves `MAKEBLOCK` scripts.
+- Decided the two open audit questions. **Insert is creatable** by naming an existing block (existence, ordinary-block and no-cycle checks; attribute records stay with the AttributeEntity flow), which completes the kind. **Legacy Polyline is update-only** with a hint pointing scripts at Polyline2D and Polyline3D, because both formats convert it on save. The generator gained an `update_only_message` for such kinds, integer coordinates are accepted in Insert scales, and the driver gained `MAKEPOLYLINE` and `MAKEBLOCK` fixtures.
+- Wrote up the cadcodec DXF reader gaps as draft issues in [cadcodec-reader-gaps.md](cadcodec-reader-gaps.md) (nothing filed): ATTDEF, boolean groups read through `as_i16()`, UNDERLAY rotation units, LEADER, DRAWINGVIEW/SECTIONLINE dispatch and TABLE merged ranges. Verifying them corrected an earlier attribution: the Spline "DXF drops weights" finding was an OCS bug (the writer emits weights only for a rational spline), now fixed by setting `flags.rational` from the weights, so Spline is complete.
+- Mapped `Ole2Frame` as update-only (queue item 21, previously blocked). OCS already builds real embedded frames (`build_embedded_ole`), which supplied the fixture the blocker was waiting for. Frame corners and the aspect lock are scriptable; the opaque storage and envelope are excluded and refused on edit. The audit proves the embedded picture survives DWG and DXF unchanged. Creation from Python remains a follow-up. The remaining blocked kinds are SectionSymbol, Region, Body, Solid3D and Surface.
+- Investigated the cadkernel path for the ACIS kinds ([cadkernel-body-path.md](cadkernel-body-path.md)). The earlier "blocked" reasoning was overstated: OCS already builds primitives, transforms bodies and runs booleans through cadkernel, and `solid_to_sat` plus `kernel_acis_body` verify each result lifts back with no loss. Two `#[ignore]` spike tests measured exact volumes and DWG and DXF round trips for a box, moved, rotated and mirrored copies, three booleans, four other primitives and a `Body` entity. The real gap is an operation channel from a script to that pipeline; the note recommends an additive `solid_operation` host method and a phased plan (Solid3D create and transform, then booleans and Body, then Region, then Surface). Booleans took about 23 s each in a debug build and need release timing first. Region, Body, Solid3D and Surface move from blocked to unblocked-by-design; SectionSymbol stays blocked.
+- Built the cadkernel operation channel and completed `Solid3D` (create and rigid move). `HostApi::solid_operation` is additive (default "unsupported"), so older hosts and plugins are unaffected; it travels as `PluginRequest::SolidOperation` and `PluginResponse::SolidResult`, and the host records its own undo step only after validation so a refused operation leaves nothing behind. The Python surface is `doc.solids.*`. Every result is verified lossless by the kernel path before it is accepted and a payload that will not lift is refused untouched. `Body` moves through the same channel and `Region` is accepted but untested. Booleans, Region creation from curves and Surface remain, in that order; booleans wait on release-build timing. Solid3D, Body and Region are now mapped read-only with the opaque payload excluded and preserved.
+- Completed `Region`. `SolidOperation::RegionFromProfile` reuses the REGION command's kernel calls and `doc.solids.region` exposes it; the lifecycle test creates regions from real circle and polyline entities and covers deletion of the source, refusals, a move, both formats and undo. Along the way `create_entity` now accepts `(x, y, z)` tuples for point properties (decided from the schema's property types) and every generated float setter accepts Python ints, so `create_entity('Circle', center=(0, 0, 0), radius=5)` works. Left: booleans (release timing first), holes and open-curve merging for regions, and `Surface`.
+- Completed `Surface` for planes, extruded open profiles, isolines and rigid moves. `SurfaceFromProfile` and `Extrude` join the kernel operations (`doc.solids.surface` and `doc.solids.extrude`); `Extrude` also gives Solid3D extrusions from closed profiles, checked against analytic volumes. The test found and fixed a real bug: Surface's `kind` field silently overwrote the entity-type `kind` key in Python dicts, so it is exposed as `surface_kind`, and a new uniqueness test guards the whole catalog. Transform now accepts surfaces (a plane stays a plane; other kinds turn generic). Left: booleans (release timing first), regions with holes, and lofted, revolved, swept and NURBS surfaces. SectionSymbol is the only unmapped kind.
+- Timed booleans in a release build (details in [cadkernel-body-path.md](cadkernel-body-path.md)). A curved box-and-cylinder boolean takes about 1 to 2.2 s, overlapping spheres 0.2 s and planar operands 1 to 2 ms, against 23 s in a debug build. The kernel refuses many curved cases quickly with a reason (`Coincident`, `CutRefused`, `NoClosedForm`), including a second cut in an already drilled box. Recommendation: add a synchronous `SolidOperation::Boolean` that surfaces the refusal and leaves the operands untouched, test it with planar operands plus one ignored curved case, and note the 30 s per-script budget. No code changed in this step.
+- Implemented `SolidOperation::Boolean` and `doc.solids.union`, `subtract` and `intersect`, as recommended by the timing study. It runs synchronously, surfaces the kernel's refusal (`Coincident`, `CutRefused`, `NoClosedForm`) with a plain-language reason and the words "nothing was changed", consumes the operands unless `keep_operands`, and records one undo step. The lifecycle test uses planar boxes (millisecond cost, exact volumes, debug-safe) and an `#[ignore]` test documents a curved refusal. With this the kernel operations in the cadkernel note are all built. SectionSymbol is the only unmapped kind.
+- Mapped `SectionSymbol`, the last unmapped kind, so all 43 canvas kinds now have explicit writes. The blocker recorded earlier was overstated: cadcodec documents `points` as canonical, says the counts equal the point count in every verified export, and provides `sync_display_fields()`, which OCS's own edits already call; OCS also renders a symbol with no style or view link. The host derives the counts and projections when `points` changes and validates that references are existing `SectionViewStyle` and `ViewRep` class objects. Every gate passes except DXF, where cadcodec reopens a top-level `SECTIONLINE` as an unknown entity (issue 5 in the cadcodec write-up, pinned by a canary). Still unverifiable here: the meaning of `raw_flags_90` and AutoCAD's acceptance of a symbol with no parent view.
+- Completed `Ole2Frame` by adding creation. `SolidOperation::EmbedPicture` and `doc.embed_picture` build the frame from a picture file with OCS's own embedding code, so a script never touches the opaque storage; PNG, JPEG and BMP are stored byte-for-byte and other formats are re-encoded as PNG. The lifecycle test now creates through Python and the new creation-rules test covers formats, aspect, origin, layer and seven refusals. 30 kinds are complete.
+- Completed `Viewport` by closing its missing canvas oracle and its derived state. The shared driver now switches the scene to the layout that owns a viewport and requires a drawn frame. The host assigns a unique id (at least 2) and derives `custom_scale = height / view_height` on every scripted create or edit, as MVIEW does, so `custom_scale` became read-only. A control showed my earlier suspicion was wrong: the default id 0 still draws a frame in a layout with no sheet viewport, so the id matters for uniqueness, not visibility. 31 kinds are complete.
+- Improved `RasterImage` linkage. A scripted image now reuses one definition per file and registers it in `ACAD_IMAGE_DICT`, which owns it; this persists through DWG and DXF. The `IMAGEDEF_REACTOR` is deliberately not written: its owner convention is ambiguous between cadcodec's struct docs and its DXF writer and cannot be checked against AutoCAD here, so the kind stays integration-tested. An exploratory spike also showed that OCS's own IMAGE command creates bare images that lose their file path on save, an OCS bug outside this plugin work that is flagged separately.
+
+### 2026-09-21: beyond entities, the layer table (`doc.layers`)
+
+Entity CRUD is at its ceiling without the cadcodec fixes (PR HakanSeven12/cadcodec#48), so work moved to
+drawing objects a script needs. New additive v7 request `TableOperation` (`LayerCreate`, `LayerModify`,
+`LayerRename`, `LayerDelete { erase_objects }`, `LayerSetCurrent`) with `HostApi::table_operation`,
+executed by `HostSession::table_operation`. Every refusal (invalid or duplicate name, bad color,
+unknown linetype, out-of-range lineweight or transparency, protected layer `0`/`Defpoints`, current
+layer, layer holding objects without `erase_objects`) is decided before the undo step is recorded, so
+nothing changes. Python: `ocs.active_document.layers` (`create`, `modify`, `rename`, `delete`,
+`set_current`, `current`, lookup and iteration). Evidence: `audit_python_layer_table_over_real_ipc`
+(19 refusals, live/DWG/DXF persistence of colour, lineweight, transparency, flags, linetype,
+description, rename following entities, `erase_objects` and one-step undo), an IPC round-trip test and a
+Python unit test. Next: text and dimension styles, linetypes, blocks, layouts; then headless commands.
+
+### 2026-09-21: text and dimension styles (`doc.text_styles`, `doc.dim_styles`)
+
+`TableOperation` grew `TextStyleCreate/Modify`, `DimStyleCreate/Modify` (DimStyle fields travel as a JSON
+object, so all 88 are settable with host validation; handles, xref fields and the name are refused),
+`StyleRename`, `StyleDelete`, `StyleSetCurrent`. The host reuses OCS's own style machinery (in-use scan,
+reference-following rename) by widening four `style_ops` methods to `pub(super)`, and additionally makes a
+renamed text style's name follow into dimension styles. Style operations require the active tab.
+Evidence: `audit_python_text_and_dim_styles_over_real_ipc` (26 refusals, live/DWG/DXF persistence, copy
+semantics, rename following references, current/delete guards, five-step undo), IPC round-trip and Python unit
+tests. Four cadcodec findings (STYLE flags and oblique units, DIMSTYLE name, `true_type_font`) are pinned by
+canaries and listed in `cadcodec-reader-gaps.md`. Next: linetypes, blocks, layouts; then headless commands.
+
+### 2026-09-21: blocks (`doc.blocks`)
+
+`TableOperation` gained `BlockCreate` (copy existing model/paper entities into a definition shifted by
+`-base_point`, optionally erasing the originals), `BlockModify` (description, explodable, uniform scale),
+`BlockRename` (inserts follow, via `Scene::rename_block`) and `BlockDelete` (refused while an insert, a
+dimension-style arrow or a multileader uses it; removes the members, markers, record and orphaned draw-order
+tables). Creation reuses `Scene::define_block_from_owned_entities`. Python: `blocks.create/modify/rename/delete`,
+lookup and iteration, records with member handles and kinds. Evidence: `audit_python_blocks_over_real_ipc`
+(18 refusals; shifted geometry and base point; inserts following a rename; original kept vs erased;
+live/DWG/DXF persistence; guarded delete; three-step undo restoring the definitions), IPC round-trip and Python
+unit tests. One more cadcodec finding (DXF drops the block description) is pinned by a canary. Not covered:
+editing a definition's contents in place, and attribute definitions inside a scripted block. Next: linetypes and
+layouts, then headless commands.
+
+### 2026-09-21: block contents (`create_entity(..., block=)`)
+
+`TableOperation::BlockEntityAdd` adds a validated entity to a definition: the host sets the owner, runs the same
+validation and reference binding as a new model-space entity, refuses viewports, raster images, block markers,
+nested attributes and self-nesting inserts (direct or transitive), then reuses the scene's block-editor routing so
+the entity gets normal preparation. Editing and deleting members already worked through the entity API; deleting a
+member now also drops its handle from the block record, because the core document leaves a removed entity
+listed (`entity_handles`). An entity-delta undo of an add still leaves the handle listed (documented scene behaviour),
+so consumers must treat `entity_handles` as candidates and confirm with `get_entity`; the Python block records
+already do. Evidence: `audit_python_block_contents_over_real_ipc` (9 refusals; create, edit, delete in a block;
+attribute definition inside a block; nested insert; live/DWG/DXF persistence; undo), IPC and Python unit tests.
+Next: linetypes and layouts, then headless commands.
+
+### 2026-09-21: linetypes and layouts (`doc.linetypes`, `doc.layouts`)
+
+`TableOperation` gained `LinetypeCreate/Modify/Rename/Delete` (simple patterns only, standard names taken, rename
+follows layers and entities, delete refused while a layer, entity, dimension style or the current setting uses it) and
+`LayoutCreate/Rename/Delete/SetCurrent/SetPage` (reusing `add_layout`, the default page setup, the sheet viewport,
+`rename_layout` plus the layout dictionary key, `delete_layout`, and the application's own `on_layout_switch`; `Model` is
+protected; `set_page` sets paper size, rotation and a custom scale and refreshes the limits). The host system variable
+`CTAB` now reports the current layout. Evidence: `audit_python_linetypes_and_layouts_over_real_ipc` (34 refusals; patterns,
+modify, rename following layers; page setup; an entity created on a sheet and not in model space; live/DWG/DXF
+persistence; deleting the current layout; four-step undo restoring the layouts, their entity and the linetype), IPC
+round-trip and Python unit tests. Not covered: complex (text/shape) linetypes, reordering layouts, plot devices and
+styles, and page-setup names. Next: headless command execution.
+
+### 2026-09-21: command runner and modify wrappers (`doc.command`, `doc.start_command`, `doc.modify`)
+
+`HostApi::run_command(CommandRequest) -> CommandOutcome` (additive v7; `Run`, `Start`, `Point`, `Text`, `Token`, `Entity`,
+`Selection`, `Enter`, `Cancel`) drives the real command through the same primitives the automation channel uses
+(`run_command_line`, `dispatch_command`, `feed_command`, `feed_active_cmd`, `CommandEscape`) and finishes each step with
+`drive_headless_task`, which is synchronous on the host thread. The earlier "nested command replay can hang" concern does not
+apply to this path: no step waits on anything that must arrive from outside, the exploration harness ran every command
+tried without a hang, and an editor or dialog a command opens is reported in `blocked_by` and closed by `Cancel`. It refuses
+while another command is active, on a denylist (`QUIT`, `EXIT`, `CLOSE*`, `NEW`, `QNEW`, `OPEN`, `SAVE*`, `RECOVER`, `SCRIPT`,
+`RUNSCRIPT`, `PY_*`), and off the active tab. It does not consult the user's automation on/off switch, which governs the
+external MCP/serve channel; a script is already something the user chose to run. Python: `doc.command`, `doc.start_command`
+(context manager that cancels a waiting command) and `doc.modify` (offset, trim, extend, fillet, move, copy, rotate, scale,
+mirror, erase). The prompt sequences were observed with `spike_command_runner_prompts` (ignored harness). Evidence:
+`audit_python_modify_wrappers_over_real_ipc` checks exact geometry for every wrapper (offset distance and side, trim and
+extend end points, fillet arc centre and radius, move, copy keeping the original, rotate, scale, mirror keeping the source,
+erase), `doc.command` and an interactive session, nine refusals (quit, new, `PY_RUN`, unknown, incomplete line, input with no
+command, second command, run while active), no command left running, and a one-step undo. IPC round-trip and Python unit tests.
+Not covered: chamfer, arrays, hatch, join, explode, break and the many other commands (reachable through `doc.command` and
+`start_command`); reading prompts for commands with a text editor; an on/off setting for script-driven commands.
+
+### 2026-09-21: more modify wrappers
+
+`doc.modify` gained `chamfer`, `array_rect`, `array_polar`, `explode`, `join`, `break_entity`, `stretch` and `lengthen`, each
+written against the prompt sequence observed in `spike_command_runner_prompts` (STRETCH needs an Enter after the crossing
+window, LENGTHEN and STRETCH end on Enter, EXPLODE and JOIN use the pre-selection because a pick at their selection prompt
+selects nothing). `audit_python_modify_wrappers_over_real_ipc` checks exact geometry for each: the chamfer line, all six
+rectangular-array members, the four polar-array members (start and half turn), the exploded segments and the removed polyline,
+the joined line without its parts, the two pieces after a break, the stretched and the lengthened end points. HATCH is left to
+`create_entity("Hatch")`: its command needs an interactive boundary pick that no scripted step can supply. Not wrapped: PEDIT,
+path and 3-D arrays, and the remaining commands, which stay reachable through `doc.command` and `start_command`.
+
+### 2026-09-21: nested input is validated (vertex validation gap)
+
+Found while writing the `explode` audit: an `LwPolyline` created from vertices that used the wrong key (`{'x': .., 'y': ..}` instead of
+`{'location': ..}`) was accepted and became zero-coordinate vertices. The generated dict-to-struct conversions for nested records
+defaulted every absent field and ignored unknown keys, so any typo inside a list of vertices, edges or faces vanished silently.
+The generator now (1) refuses an unknown key in every nested record, naming the keys it takes, and (2) enforces a manifest list,
+`required_struct_fields`, of the fields that define a nested record's geometry: `LwVertex.location`, `Vertex2D.location`,
+`Vertex3D.location`, `Vertex3DPolyline.position`, `PolygonMeshVertex.location`, `PolyfaceVertex.location`, `MLineVertex.position`,
+`LineEdge.start/end`, `CircularArcEdge.center/radius`, `EllipticArcEdge.center/major_axis_endpoint`, `PolylineEdge.vertices` and
+`SectionSymbolPoint.point`. A `None` counts as missing. Everything else in a nested record still defaults when absent. Evidence:
+`audit_python_nested_input_is_validated_over_real_ipc` (eight refusals with the right messages for LwPolyline, Polyline2D and
+PolygonMesh; nothing invalid reaches the drawing; the valid forms still create), and every existing per-kind lifecycle audit still passes.
+
+### 2026-09-21: PEDIT and the remaining arrays
+
+`doc.modify` gained `array_path`, `array_3d`, `polyline_close`, `polyline_open`, `polyline_width`, `polyline_reverse` and `polyline_join`,
+written against the prompts observed in `spike_command_runner_prompts` (PEDIT offers to turn a line or arc into a polyline and the wrapper
+accepts; the join option takes a selection, and its Enter completes the whole command). The default pick point for a polyline is its first
+vertex. `audit_python_modify_wrappers_over_real_ipc` checks: closed and opened flags, the widened polyline, the reversed vertex order, the
+joined polyline's three vertices with its line consumed, a line turned into a widened polyline (and the line gone), all five path-array
+positions (2600 to 2650 in 12.5 steps), and all eight members of the 3-D array (x 2700/2720, y 0/10, z 0/30). Finding: PEDIT's line-to-polyline
+step needs between 2 and 4 MiB of stack in a debug build, more than a test thread's 2 MiB, so that audit runs on a 64 MiB thread; the
+application's main thread has 8 MiB, and a release build uses far less. Not wrapped: PEDIT fit, spline, decurve, linetype generation and
+vertex editing.
+
+### 2026-09-21: guardrails (`SCRIPTCOMMANDS`, stack)
+
+**On/off setting.** A saved user preference, `UserSettings::script_commands` (on by default, so an existing config keeps
+scripts allowed), toggled by the `SCRIPTCOMMANDS [0|1]` command, gates `HostApi::run_command`: while it is off every `Run`,
+`Start` and input request is refused (`Cancel` stays allowed so a waiting command is never stranded) with a message that says how to turn it back on. The runner refuses the command
+itself (it joins `QUIT`, `NEW`, `PY_*` and the rest on the denylist), so a script cannot switch it. It is a command and a
+persisted flag only; there is no Options-page control, which would need locale and layout work in files outside this feature.
+Evidence: `script_commands_setting_gates_the_runner` (default on; a script cannot change it; the user turns it off and nothing
+runs, `Run` and `Start` both refused, no entity added; back on and it runs) and `script_commands_default_on_and_survive_a_round_trip`.
+Checked that the test did not write the setting into the real user config.
+
+**Stack.** The planned large-stack thread for command steps was not built, on the evidence: the native builds already link with
+at least 8 MiB (`.cargo/config.toml` raises Windows to 16 MiB), the deepest step found (PEDIT converting a line to a polyline)
+needs 2 to 4 MiB in a debug build, and the nesting depth is fixed because `PY_*` is refused, so it cannot recurse. Moving the step
+to a helper thread would be unsound here (the editor state is not `Send` and some of it has thread affinity), and the alternative,
+a stack-growing dependency such as `stacker`, adds a crate to H7's tree to guard a case that cannot occur. The 64 MiB thread in the
+PEDIT audit stays, because a test thread gets only 2 MiB.
+
+### 2026-09-21: cadcodec PR #51 (text and dimension style DXF fixes)
+
+Second small upstream PR, [HakanSeven12/cadcodec#51](https://github.com/HakanSeven12/cadcodec/pull/51): STYLE generation
+flags (group 71 was hard-coded to 0), the STYLE oblique angle (group 50 is degrees; it was written and read as raw radians)
+and the DIMSTYLE text-style name (resolved from the group 340 handle). Three commits, three regression tests, independent of
+#48 (merged locally with it; the combined suite passes). Not included: `true_type_font` and the block description, which need
+an XDATA layout that cannot be verified here. OCS still pins the unfixed revision, so the canaries in
+`audit_python_text_and_dim_styles_over_real_ipc` still assert the wrong result until #51 is merged and OCS repins.
+
+### 2026-09-21: Linux and Windows verification
+
+The change was built in release on Ubuntu and Windows runners with the Python plugin staged beside the executable
+(`plugins/opencad.python`, where the host looks for it on both platforms), and the real-IPC plugin tests ran against
+that build: **60 of 60 on each** (unsigned portable packages, built by a fork-only workflow that is not part of this change).
+The first Windows run failed two tests because the harness substituted the Windows temp directory (`C:\Users\...`) into a
+Python string literal, where `\U` is a unicode escape; that was a test-harness path problem, not a product one, and is fixed by
+handing the scripts a forward-slash path. Not covered: the whole workspace suite on Windows, the macOS-only bundle path, and an
+installer (AppImage or MSI) that includes the plugin.
+
+### 2026-09-21: pull-request check (`python-host-check.yml`)
+
+`.github/workflows/python-host-check.yml` runs on `pull_request` (path-filtered to the plugin API, the plugin, the host's plugin and command
+files, settings and the lockfile), on a `pr-check-*` tag and by hand, on `ubuntu-22.04` and `windows-latest`. Steps: the plugin API tests
+(`--features host`), staging the bundled plugin and building the runner, the plugin crate tests, the Python model unit tests, and the host's
+real-IPC tests. It fails outright if the staged plugin or the runner is missing, because those tests otherwise skip and report success. First run
+(`pr-check-1`, commit `1f8cbb81`, all green on both platforms): 115 plugin API tests, 20 plugin crate tests, 16 Python model tests and 60 real-IPC
+host tests on each. Debug build, so a cold run is about 30 minutes and a cached one much less. The whole lib suite is deliberately not run by that workflow, because `main`'s own `Tests` workflow (`cargo test --workspace --locked`, added upstream on 21 September) runs it on every pull request. Against the merged tree that command gives 1,805 passed and 1 failed locally on macOS, `fonts_parse_and_resolve`, which also fails on pristine `main` there.
+
+### 2026-09-21: merged upstream `main` (25 commits)
+
+Merged `origin/main` at its head (no conflicts). Upstream added `.github/workflows/ci.yml` (`cargo test --workspace --locked` on Linux for every
+pull request, `LC_ALL=C`), removed the Nix files, and added parametric-constraint and viewport-plot changes. Re-verified on the merged tree: the
+plugin gate (60 real-IPC host tests, 115 plugin API, 20 plugin crate, 16 Python model), the wasm check, and the upstream workspace command with
+`--no-fail-fast` (1,805 passed, 1 failed: `fonts_parse_and_resolve`, which fails on pristine `main` on this Mac too; `arc_grips_drive_center_start_and_end_but_not_midpoint`
+now passes, fixed upstream). The change is 72 files, +30,705 / -178 against current `main` (fork-only workflow excluded).
+

docs/plugin-host-model-coverage-ledger.md

@@ -0,0 +1,59 @@
+# OCS canvas kind coverage ledger
+
+Use with [the completion plan](plugin-host-model-completion-plan.md). This ledger is current as of 21 September 2026 (the object tables, block contents and command runner added since are described in [the design note](plugin-host-model.md) and the plan's progress log; they are not entity kinds): **43 of 43 canvas kinds have explicit geometry writes** (41 creatable, plus update-only legacy `Polyline` and `Body`), **31 kinds are complete**, and none remains layer-only. `Mapped` means at least one non-layer field is exposed for Python writes; it does **not** mean the kind passes the completion gate. `Update-only` means Python creation is unavailable. `Layer-only` means raw inspection and canvas layer edits exist, but geometry is not mapped. Record actual evidence or a blocking issue before changing any status to `Complete`.
+
+**Rows blocked at W by cadcodec.** Fixes for six of the DXF bugs behind them are submitted as [HakanSeven12/cadcodec#48](https://github.com/HakanSeven12/cadcodec/pull/48) (ATTDEF fields, boolean group codes for Helix and Light, UNDERLAY rotation, LEADER link and vectors, DRAWINGVIEW/SECTIONLINE dispatch, TABLE merged ranges). OCS still pins the unfixed revision `5b682ed`, so those rows stay blocked and their canaries still assert the wrong result; the expectation is that they flip and the rows move to `Complete` once #48 is merged and OCS repins. That has been checked in cadcodec's own round-trip tests, not yet in OCS.
+
+Completion gate codes: **C** = create through Python document model; **R** = read; **E** = edit defining geometry and another property; **D** = delete; **U** = undo/redo and atomic failure; **I** = real IPC plus GUI/canvas pick or observable behavior; **W** = DWG and DXF save/reopen; **V** = invalid-input checks and untouched-field/reference preservation; **P** = build and load the in-tree bundled plugin with a manifest matching the host toolchain and acadrust source. A kind is `Complete` only when **C/R/E/D/U/I/W/V/P** all pass and its property catalog matches implementation. `Blocked` requires a specific dependency or failing fixture.
+
+| Kind | Baseline | Gate evidence / blocker |
+|---|---|---|
+| Point | **Complete** | Exercised: `location`, `thickness`. Rejects non-finite location, thickness and axis angle and a zero normal, which the audit found were previously accepted (thickness and normal) or unchecked at creation. `audit_python_point_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| Line | **Complete** | Exercised: `end`, `thickness`. Existing endpoint, undo, selection and pick coverage plus the second-property edit the earlier row asked for. Rejects non-finite endpoints and thickness and a zero normal (thickness was previously accepted). `audit_python_line_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| Circle | **Complete** | Exercised: `radius`, `center`. Rejects a non-positive or non-finite radius, non-finite center and thickness, and a zero normal. `audit_python_circle_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| Arc | **Complete** | Exercised: `end_angle`, `radius`. Rejects a non-positive radius, non-finite angles (previously accepted), center and thickness, and a zero normal. `audit_python_arc_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| Ellipse | **Complete** | Exercised: `minor_axis_ratio`, `end_parameter`. The audit found Ellipse had no validation at all; it now requires a nonzero major axis, a ratio within (0, 1], finite parameters and a nonzero normal. `audit_python_ellipse_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| Polyline | **Update-only (decision)** | Decision (2026-09-20): the legacy `Polyline` (3-D vertices) is not creatable from Python, because both file formats save it as `Polyline3D` and it would silently change kind on the first save. Creating one now fails with a message that names `Polyline2D` and `Polyline3D`. Existing `Polyline` entities remain editable: `audit_python_polyline_lifecycle_over_real_ipc` (host-made fixture) passes E/D/U/I/V with vertex and closed edits, canvas wires, rejection of short and non-finite vertex lists, an atomic rollback and three-step undo/redo, and pins the reopen behavior (both DWG and DXF return a `Polyline3D` with the vertices and closure intact). Scripts should create `Polyline2D` or `Polyline3D`. |
+| Polyline2D | **Integration-tested / kind changes on DXF save** | Exercised: `vertices`, `closed`, `thickness`. Passes every gate in DWG. DXF reopens a 2-D polyline as an `LwPolyline` (vertices, closure and width survive, but the kind changes and `thickness` is not part of that record's digest here); pinned by a canary expectation. `audit_python_polyline2d_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| Polyline3D | **Integration-tested / blocked at W by the DWG format (elevation)** | Exercised: `vertices`, `elevation`. Passes every gate in DXF; DWG does not store a 3-D polyline's `elevation`, so it reopens as 0 (pinned by a canary). Vertices persist. `audit_python_polyline3d_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| LwPolyline | **Complete** | Exercised: `vertices` (with a bulge), `is_closed`, `constant_width`. Rejects fewer than 2 vertices, non-finite locations, bulges and widths, a negative constant width and a zero normal. `audit_python_lwpolyline_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| Spline | **Complete** | Exercised: `control_points`, `weights`. Validation covers degree, control-point count, knot count and order, weights and finite points. The host sets `flags.rational` whenever weights are present, because the DXF writer emits group 41 only for a rational spline; the audit first showed weights vanishing in DXF and traced it to that missing flag (an OCS bug, not a cadcodec one), now fixed. `audit_python_spline_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P with DWG and DXF reopen, re-edit, atomic rollback and three-step undo/redo. |
+| Text | **Complete** | Exercised: `text`, `rotation`, `height`. Rejects a non-positive height (previously accepted), a non-positive width factor, non-finite placement and angles, and a zero normal. Style and alignment fields are mapped but not individually exercised. `audit_python_text_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| MText | **Complete** | Exercised: `text`, `rectangle_width`, `rotation`. Rejects a non-positive height (previously accepted), a negative width, non-finite placement, a non-positive line-spacing factor and a zero normal. Attachment, columns and background fields are mapped but not individually exercised. `audit_python_mtext_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| Ray | **Complete** | Exercised: `base_point`, `direction`. Unit-direction and finite-point validation already existed; the audit added the full DWG and DXF reopen and re-edit gate. `audit_python_ray_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| XLine | **Complete** | Exercised: `base_point`, `direction`. Same as Ray. `audit_python_xline_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| Solid | **Complete** | Exercised: `fourth_corner`, `thickness`. Finite corners, thickness and normal validation already existed; the audit added the full gate. `audit_python_solid_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| Face3D | **Complete** | Exercised: `third_corner`, `invisible_edges`. Finite corners and known edge bits validation already existed; the audit added the full gate. `audit_python_face3d_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real runner) passes C/R/E/D/U/I/W/V/P: creation, a two-or-more-property transaction edit with the entity's common data, identity and selection preserved, canvas wires, invalid-input rejection with an atomic multi-entity rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. The audit added the shared `validate_basic_entity` (creation must be valid; an edit is refused only for problems it introduces, so already-invalid legacy values stay editable). |
+| Insert | **Complete** | Decision (2026-09-20): Insert is creatable. A script names an existing block with `block_name` and a placement; the host does not generate attribute records, because attributes stay with the `AttributeEntity` flow that already creates them from the block's ATTDEFs. Writable: `block_name` (fixed after creation; the mutation check refuses a different block), `insert_point`, `x_scale`, `y_scale`, `z_scale`, `rotation`, `normal`, `column_count`, `row_count`, `column_spacing`, `row_spacing`. Creation and rename rules: the block must exist, must not be model or paper space, and must not make a block contain itself directly or through nested inserts; scales must be finite and nonzero, array counts positive, and the name non-empty. An edit that keeps the block name is exempt from the block checks so a legacy insert of a missing block stays editable. `audit_python_insert_lifecycle_over_real_ipc` (shared driver, host-made block) passes C/R/E/D/U/I/W/V/P: creation by block name, a six-property transaction edit, canvas wires, rejection of zero scale, non-finite rotation and point, zero array count, zero normal and an unknown block, an atomic rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. `audit_python_insert_creation_rules_over_real_ipc` covers unknown block, model-space block, bad scale, zero count, empty name, direct self-insertion and indirect nesting cycles. Not covered: MINSERT (`dwg_minsert`) and attached-attribute creation, which stay excluded and preserved. |
+| Tolerance | **Complete** | `staged_python_tolerance_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P with the staged API v7 plugin: high-level create/read/transaction edit/delete; insertion, direction, and text edits; live canvas selection; grouped undo/redo; invalid direction and missing style atomic rollback; exact untouched common/style/private-field preservation; and edited DWG plus DXF reopen. Host-owned coverage exposes placement, direction, normal, text, style name, height and gap; style handle is read-only and the undocumented DWG short remains unmapped. `tolerance_geometry_and_style_references_are_validated` and the existing Tolerance tessellation tests cover reference and rendered-frame behavior. |
+| Shape | **Complete** | `staged_python_shape_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P with a generated parser-valid SHX file and a real shape-file `TextStyle`: high-level create/read/transaction edit/delete; insertion, size, rotation and width-factor edits; live canvas selection; grouped undo/redo; invalid size and missing style rollback; exact identity/style/common-field preservation; and DWG plus DXF reopen. Each live and reopened document renders the three-point SHX glyph rather than the placeholder. Host-owned reference binding writes the stable style handle needed by DWG. The DXF fallback now searches all `is_shape_file` styles, preserving named-style glyph resolution after reopen. |
+| AttributeDefinition | **Integration-tested / blocked at W by acadrust (DXF ATTDEF reader)** | Host commit `5b854bd1` maps block ownership plus every stable ATTDEF field except the nested `embedded_mtext` payload, which is snapshot-readable and preserved untouched. Two staged tests cover it. `staged_python_attribute_definition_lifecycle_over_real_ipc` passes with a real block record, Block/BlockEnd markers and a linked Insert. The 2026-09-20 audit `audit_python_attribute_definition_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, host-made block) compares **every writable field** through both formats: creation with non-default tag, prompt, value, placement, alignment point, height, rotation, width factor, oblique angle, alignments, all attribute flags, field length, generation flags and lock; a nine-property transaction edit; canvas wires; eight rejection cases (whitespace tag, non-positive height and width factor, missing style, owner change, zero normal, non-finite rotation, unknown alignment) plus an atomic rollback; DWG reopen with the **complete** edited state and re-edit; deletion; and three-step undo/redo. **W blocker, revalidated on acadrust `5b682ed`:** the DXF writer emits every ATTDEF group, but the reader handles only groups 1, 2, 3, 10, 40, 50, 280 and 101, so a DXF reopen keeps tag, prompt, value, insertion point, height and rotation and resets the alignment point, both alignments, width factor, oblique angle, all attribute flags (invisible, constant, verify, preset), field length, generation flags, lock and text style to defaults. This is now pinned by canary expectations for both the edit and the re-edit. Not `Complete` until the reader is extended; the fix belongs in cadcodec's `read_attdef`. `embedded_mtext` mutation remains unsupported pending linked-layout validation. |
+| AttributeEntity | **Complete** | OCS commit `cf2a9235` and adapter commit `9c6b5c3` make nested ATTRIB records addressable by handle while retaining canonical storage in `Insert.attributes`. Host validation binds tag to a definition in the Insert's block, validates placement/text geometry and style references, keeps owner and definition handles read-only, and preserves embedded MTEXT. `staged_python_attribute_entity_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P with a real block, ATTDEF and Insert: high-level create/read/transaction edit/delete, parent selection, rendered text, atomic invalid tag/height/owner rejection, edited and deleted DWG/DXF reopen, and three-step undo/redo. `nested_insert_attribute_crud_uses_parent_storage_and_undo` additionally proves the child never becomes an orphan flat entity in the host document. |
+| Hatch | **Complete** | OCS commit `98b56ef6` and adapter commit `a9b5de8` expose solid and patterned Hatches with elevation/normal, complete pattern definitions, pattern controls, style, association state, boundary paths and seed points. Nested tagged boundary edges use the reusable `{kind, value}` adapter form. Host validation requires closed finite loops, validates line/arc/ellipse/polyline/spline payloads and stored pattern lines, resolves associative boundary handles, and preserves gradient and MPOLYGON payloads as explicitly unsupported. `staged_python_hatch_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P: Python solid creation, patterned boundary edit, live render-model pattern/boundary checks, selection, atomic invalid scale/association/open-loop/unmapped-property rejection, edited and deleted DWG/DXF reopen, post-reopen edits, and three-step undo/redo. |
+| Leader | **Integration-tested / blocked at W by acadrust** | Fields mapped writable: `vertices` (≥2 finite points, not all coincident), `annotation_handle`, `creation_type`, `path_type`, `dimension_style`, `arrow_enabled`, `hookline_enabled`, `hookline_direction`, `text_height`, `text_width`, `normal`, `horizontal_direction`, `block_offset`, `annotation_offset`. Read-only: `origin`, `dimension_gap`, `arrowhead_type`, `arrow_size`, `byblock_color`. `override_color` is writable through the new generator `Color` form (`{'kind': 'Rgb', 'value': {'r','g','b'}}`, `Index`, `ByLayer`, `ByBlock`, `None`). Unmapped but preserved on edit: the `dwg_unknown_*` fields. Host reference binding validates that `annotation_handle` exists, is not the leader itself, matches `creation_type` (Text/MText, Tolerance, Insert; `NoAnnotation` forbids a handle) and that `dimension_style` exists; nothing is silently defaulted. `staged_python_leader_lifecycle_over_real_ipc` passes C/R/E/D/U/I/V/P against acadrust `7ea4247`: linked Text annotation, path/height/arrow/offset transaction edit with untouched-field preservation, GUI pick grouping (scripted selection stays exact), seven single-edit rejections plus a cross-entity atomic rollback, four-step undo/redo, real render linework, DWG and DXF reopen and re-edit. Erasing a leader also erases its annotation (scene leader grouping); undo restores both. **W blockers (engine, recorded as canary assertions in the test):** (1) the DXF writer never emits group 340, so a DXF save unlinks the annotation; (2) DXF reads drop `annotation_offset` (group 213 is written but not reassembled); (3) DWG R2010+ does not store `text_height`, `text_width` or `hookline_enabled` (acadrust writes them only for R13–R2007 / R13–R14); (4) neither writer stores `override_color`, so it reopens as `ByLayer` in DWG and DXF. Not `Complete` until the engine round-trips (1) and (2); (3) needs a decision to document or make read-only. |
+| MLine | **Complete** | Writable: `vertices` (raw vertex dicts; a script may pass only `position`), `flags` (integer, unknown bits rejected), `justification`, `normal`, `scale_factor`, `style_name`. Read-only: `start_point`, `style_handle`, `style_element_count`. Host validation requires ≥2 finite non-coincident vertices, ≥3 for a closed multiline, a finite nonzero scale and normal, an existing non-empty `MLineStyle`, and per-vertex segments that are either empty or match the style element count. Vertex `direction`/`miter`, segment layout and per-element miter offsets (justification and scale included) are host-derived by `normalize_scripted_mline` on every scripted create or edit, reusing the drawing command's `rebuild_mline_geometry`/`sync_mline_element_parameters`; dash and fill cuts survive an edit unless a vertex moves. `staged_python_mline_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P: create against the Standard style, a three-vertex/scale/justification transaction edit with untouched-field preservation, corner miter widening and element offsets checked, real `mline_lines` linework before and after DWG and DXF reopen, nine single-edit rejections plus a cross-entity atomic rollback, re-edit after reopen in both formats, deletion, and three-step undo/redo. Known limit: switching to a style with a different element count is rejected until the script also clears the vertices' `segments`; only the rejection is covered by the integration test. |
+| Dimension | **Complete** (all 9 subtypes) | `EntityType::Dimension` wraps a nine-variant enum, so the adapter uses a hand-written flat model (`dimension_model.rs.inc`, wired in through the manifest's `manual_kinds`) and the coverage catalog lists its properties through the policy's `synthetic` section. Python sees `subtype` (fixed at creation), the shared base fields (`text`, `style_name`, `normal`, `text_middle_point`, `attachment_point`, `text_rotation`, `horizontal_direction`, `flip_arrow1/2`, `text_user_positioned`) and only the fields of that subtype; a field from another subtype is rejected, not ignored. `actual_measurement` and the base definition point are host-derived (`normalize_scripted_dimension`, the same recompute grip edits use). Unmapped but preserved: `user_text`, `insertion_point`, `block_name`, version and DWG flags, style overrides in XDATA. Per-subtype status, all verified by `staged_python_dimension_lifecycle_over_real_ipc` (C/R/E/D/U/I/W/V/P; measurement and canvas wires checked for each, DWG and DXF reopen recorded per subtype): Linear (10), Aligned (5), Radius (5), Diameter (10), Angular3Pt (90°), Angular2Ln (90°), Ordinate (5), Arc (5·π/2), LargeRadial (6) — every one creates, reads, derives the right measurement, renders wires, and keeps its measurement through DWG and DXF. Edits (Linear second point/text/attachment, Radius definition point) update the measurement, nine rejection cases plus a cross-entity atomic rollback and three create-time rejections leave the document untouched, and post-reopen re-edit passes in both formats. Not covered: text formatting overrides, arrowheads and other DIMSTYLE overrides stored in XDATA, the anonymous `*D` block. The subtype-specific field meanings for the angular subtypes follow the DXF group-code layout rather than the acadrust convenience constructors. |
+| MultiLeader | **Complete** | Mapped through the generic generator, which gained support for `Color`, `LineWeight`, mixed unit/payload enums, fixed `[f64; N]` arrays, bitflags-2 newtypes and per-type module paths for this kind. Writable: `content_type`, `path_type`, `line_color`, `line_weight`, `enable_landing`, `enable_dogleg`, `dogleg_length`, `arrowhead_size`, `text_color`, `text_frame`, the four text attachments, attachment direction/point, `text_alignment`, `text_angle_type`, `text_direction_negative`, `scale_factor`, `enable_annotation_scale`, `extend_leader_to_text`, block content fields, the reference handles (`style_handle`, `text_style_handle`, `arrowhead_handle`, `line_type_handle`, `block_content_handle`) and `context`, which merges as a patch so a script can change `text_string` without resetting leader roots. Read-only: `dwg_version`, `property_override_flags`, `text_align_in_ipe` and the entity-level `text_height` (neither writer stores it; set `context.text_height`). Excluded but preserved: `arrowhead_overrides`, `block_attributes`. Host validation checks finite/positive scale, height, dogleg and arrow sizes, finite context geometry and transform, non-empty leader lines, content-type/context consistency, and that every referenced handle exists as the right object kind. `staged_python_multileader_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P: MText creation with a three-point leader root, a partial-context edit that replaces the path (four points), text, text location, dogleg and colour while preserving scale/content/common fields, canvas wires, eleven rejection cases plus a duplicate-handle atomic rollback, DWG and DXF reopen (text, path, dogleg, `context.text_height`, colour) with post-reopen re-edit, and three-step undo/redo. Not covered: block-content MultiLeaders (no block fixture yet), tolerance content, and style-defined defaults. |
+| Table | **Complete** | Mapped through the generic generator (now also handling tuples and `usize`, with the generic `LegacyBorderOverrides<T>` fields excluded and preserved). Writable: `insertion_point`, `horizontal_direction`, `normal`, `table_style_handle`, `rows`, `columns`, `merged_ranges`, `break_spacing`, `break_flow_direction`, `break_options`. Read-only: `block_name`, `block_record_handle`, `data_version`, `value_flags`, the override flags, `name`, `description`, `field_handles`, `base_style`, `break_data`, `break_ranges`, `legacy_style_override`. Creation yields the engine default 3x3 grid; scripts read `rows`/`columns`, modify or extend them and assign them back (rows and columns replace wholesale, so copy an existing row dict when adding one). Host validation requires a non-empty grid, positive finite row heights and column widths, every row to have exactly one cell per column, finite cell and content geometry, merged ranges inside the grid and non-overlapping, and existing table-style, cell text-style and cell block handles. `normalize_scripted_table` mirrors `merged_ranges` onto the origin cell's `merge_width/height` on every scripted change to the ranges. `staged_python_table_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P: default-grid creation, a row append, column-width edit, a text cell, a three-column merge and break spacing in one transaction with untouched rows/columns/style/common fields preserved, canvas wires, ten rejection cases plus an atomic rollback, DWG and DXF reopen (row count, width, cell text, insertion) with re-edit, and three-step undo/redo. Format notes: DWG restores `merged_ranges` but not per-cell merge dimensions; DXF restores the cell dimensions but its reader does not rebuild `merged_ranges` (recorded by a canary assertion); both keep the merge. Not covered: the anonymous table block is not regenerated, cell styles and formats beyond text, linked data and field content. |
+| PolygonMesh | **Complete** | Writable: `flags`, `m_vertex_count`, `n_vertex_count`, `m_smooth_density`, `n_smooth_density`, `smooth_type`, `elevation`, `normal`, `vertices` (each `{location, flags}`; a vertex's own common data is not scripted and defaults). Host validation requires M and N of at least 2, exactly M×N vertices, non-negative densities, finite elevation and locations, and a nonzero normal, so inconsistent counts are refused before any mutation. `staged_python_polygon_mesh_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`) passes C/R/E/D/U/I/W/V/P: a 3×3 grid, a vertex move plus density and cubic smoothing in one transaction, canvas wires, seven rejection cases plus an atomic rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. |
+| PolyfaceMesh | **Complete** | Writable: `elevation`, `flags`, `normal`, `start_width`, `end_width`, `smooth_surface`, `thickness`, `vertices` (location, flags, bulge, widths, tangent, id) and `faces` (four indices, flags, optional colour). `seqend_handle` is read-only and preserved. Host validation requires at least 3 finite vertices and 1 face, every face index within the vertex count (a negative index hides that edge, 0 marks an unused corner), at least 3 indices per face, and finite widths, thickness and elevation. `staged_python_polyface_mesh_lifecycle_over_real_ipc` passes the full gate: two triangles, a vertex move plus a new vertex and a hidden-edge face in one transaction, canvas wires, six rejection cases plus an atomic rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. |
+| Mesh | **Complete** | Writable: `blend_crease`, `subdivision_level`, `vertices`, `faces`, `edges` (start, end, optional crease), `override_option`; `version` is read-only. Host validation requires at least 3 finite vertices, faces of at least 3 in-range indices, edges with distinct in-range endpoints and a finite non-negative crease, and a non-negative subdivision level, so out-of-range topology is rejected before mutation. `staged_python_mesh_lifecycle_over_real_ipc` passes the full gate: a quad with a creased edge, an added vertex and triangle plus subdivision level 1 in one transaction, canvas wires, seven rejection cases plus an atomic rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. |
+| Helix | **Integration-tested / blocked at W by acadrust (DXF handedness)** | Writable generating parameters: `axis_base_point`, `start_point`, `axis_vector`, `radius` (the top radius; the base radius is the start point's distance from the axis), `turns`, `turn_height`, `handedness`, `constraint`. Read-only: `spline`, `major_version`, `maintenance_version`. The host rebuilds the derived NURBS spline with OCS's own helix builder on every scripted create or parameter edit (`normalize_scripted_helix`), so the spline always matches the parameters. Host validation requires finite positive radius, turns and turn height, a nonzero axis and a start point off the axis. `staged_python_helix_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`) passes C/R/E/D/U/I/V/P: creation with a derived spline ending at z = turns × turn height, a turns and handedness edit that regenerates it, canvas wires, seven rejection cases plus an atomic rollback, DWG reopen and re-edit, DXF reopen and re-edit, and three-step undo/redo. **W blocker (engine, pinned by a canary assertion):** the DXF reader parses boolean group 290 as an `i16` and never applies it, so a clockwise helix reopens counter-clockwise from DXF while DWG keeps it. Not `Complete` until the reader is fixed. |
+| RasterImage | **Integration-tested** | Writable: `file_path` (creation only; a later change is rejected because the image definition owns it), `insertion_point`, `u_vector`, `v_vector` (world units per pixel), `flags`, `clipping_enabled`, `brightness`, `contrast`, `fade`, `clip_boundary`. Read-only: `size` (pixel size, taken from the file), `class_version`, `definition_handle`, `definition_reactor_handle`. Creating from a script requires a readable image file: the host reads its pixel size, creates the `ImageDefinition` object, links it, and sets `size` and a whole-image clip boundary from the file. Host validation requires finite, non-parallel `u`/`v` vectors, brightness/contrast/fade within 0..=100, known display flags, finite clip vertices, at least 2 clip vertices when clipping is enabled, and an existing definition. `staged_python_raster_image_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, real PNG fixture) passes C/R/E/D/U/I/W/V/P inside OCS: creation with a host-made definition, placement/scale/brightness/contrast/fade and clip edit in one transaction, canvas wires, eight rejection cases plus an atomic rollback, DWG and DXF reopen with the definition link and file path intact, re-edit, and three-step undo/redo. **Linkage (updated 2026-09-20):** a scripted image now reuses one `ImageDefinition` per file and registers each definition in `ACAD_IMAGE_DICT` under the file's name (a `_2`, `_3` suffix keeps keys unique), creating that dictionary under the root when the drawing has none, and the dictionary owns the definition, as for an image AutoCAD attached. `audit_python_raster_image_definition_linkage_over_real_ipc` checks two images of one file sharing a definition, a third file getting its own, the entries resolving with the right owner, and all of it surviving DWG and DXF reopen and an undo without a dangling entry. **Why not `Complete`:** the host still writes no `IMAGEDEF_REACTOR`: cadcodec's struct documents the reactor's owner as the definition while its DXF writer follows a different convention, and AutoCAD's behavior cannot be checked here, so guessing risks a structure AutoCAD repairs or rejects. **Related finding:** OCS's own IMAGE command creates a bare `RasterImage` with no definition, and a save through either writer drops its file path (`spike_raster_image_definition_persistence`), while the definition-linked form keeps it. Editing an existing definition (file path, resolution) is out of scope. |
+| Wipeout | **Complete** | Writable: `insertion_point`, `u_vector`, `v_vector` (the region's world extent), `size`, `flags`, `clipping_enabled`, `brightness`, `contrast`, `fade`, `clip_mode`, `clip_type` and `clip_boundary_vertices` (normalized image coordinates, -0.5..0.5). Read-only: `class_version`, `definition_handle`, `definition_reactor_handle`. Scripted creation matches OCS's native WIPEOUT command, which also leaves the definition link unset. Host validation requires finite non-parallel `u`/`v` vectors, a positive `size`, brightness/contrast/fade within 0..=100, known flags, finite clip vertices, exactly 2 vertices for a rectangular clip and at least 3 for a polygonal one. `staged_python_wipeout_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`) passes C/R/E/D/U/I/W/V/P: rectangular creation, a switch to a three-vertex polygonal inside-clip with a move in one transaction, canvas wires, eight rejection cases plus an atomic rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. |
+| Underlay | **Integration-tested / blocked at W by acadrust (DXF rotation units)** | Writable: `underlay_type` and `definition_handle` (both fixed by the definition: creation names an existing `UnderlayDefinition`, and a mismatched type or missing definition is rejected), `insertion_point`, `x_scale`, `y_scale`, `z_scale`, `rotation`, `normal`, `flags`, `contrast`, `fade`, `clip_boundary_vertices`, `clip_inverted`. The file path and page live on the definition object, which scripts cannot create or list yet; they reference one the drawing already owns. Host validation requires finite nonzero scales, a finite rotation, a nonzero normal, contrast/fade within 0..=100, known flags, finite clip vertices (none, or at least 2) and an existing definition of the same type. `staged_python_underlay_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle` with a fixture PDF definition) passes C/R/E/D/U/I/V/P and DWG W: creation, a placement/scale/rotation/contrast/fade/clip transaction, canvas wires, eight rejection cases plus an atomic rollback, DWG reopen and re-edit, and three-step undo/redo. **W blocker (engine, pinned by canary assertions):** DXF stores the rotation in degrees but the reader returns it unconverted, so 0.5 rad reopens as 28.6 and each further DXF save-reopen compounds it (1641.4 after a second), silently corrupting the rotation. Not `Complete` until the reader converts degrees back to radians. Not covered: creating definitions from a file path, DWF/DGN fixtures. |
+| Viewport | **Complete (OCS round trip)** | Writable: `center`, `width`, `height`, `status`, `view_center`, `view_direction`, `view_target`, `lens_length`, `front_clip_z`, `back_clip_z`, `view_height`, `twist_angle`, `frozen_layers` (layer handles), `render_mode`, `circle_sides`, `ucs_icon_visible`. Read-only: `id`, `custom_scale`, snap and grid settings, UCS fields, `clip_boundary_handle`, `style_sheet`, shade-plot, background, visual-style and sun handles, lighting, `ambient_color`, `elevation`. Reference rules: the owner must be a paper-space layout block and every frozen-layer handle an existing layer. **Derived by the host (new 2026-09-20), as the MVIEW command does:** a scripted viewport gets an `id` unique in its layout and at least 2 (max existing plus one), and `custom_scale` is `height / view_height`, recomputed whenever either changes, so `custom_scale` is now read-only (setting the scale directly would have let it drift from the geometry). Host validation requires finite centers, positive width, height, view height, lens length and scale, a nonzero view direction, finite clip planes and twist, and at least 3 circle sides. **Canvas oracle (new):** the shared driver now activates the layout that owns the viewport (`Scene::set_current_layout`) and requires the viewport to draw a frame both after creation and after the edit. `staged_python_viewport_lifecycle_over_real_ipc` passes C/R/E/D/U/I/V/W/P: creation in the paper-space block, a move/resize/view-height/twist/frozen-layer transaction, seven rejection cases plus an atomic rollback, DWG and DXF reopen with re-edit, and three-step undo/redo. `audit_python_viewport_ids_and_scale_over_real_ipc` checks unique ids (2, 3, 4), the derived scale on create and after a zoom and a resize, an id kept across edits, a rejected direct `custom_scale` write, and that every viewport draws a frame. A control showed that the engine default id 0 is **not** invisible in a layout with no sheet viewport (it draws a frame), which corrects an earlier suspicion; the derived id matters for uniqueness. Not covered: clip boundary entities (`clip_boundary_handle` is read-only and preserved), non-rectangular viewports, and AutoCAD acceptance of the written viewports, which cannot be tested here. |
+| ViewBorder | **Integration-tested / blocked at W by acadrust (DXF kind)** | Writable: `min`, `max`, `center` (2-D pairs), `scale`, `rotation_angle`, `active_viewport` and `scale_handle` (both required at creation). `version` is read-only. Reference rules: `active_viewport` must be an existing Viewport entity and `scale_handle` an existing `Scale` object. Host validation requires finite bounds with `min` below `max` on both axes, a positive scale and a finite rotation. `staged_python_view_border_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`, driver-made viewport and scale fixtures) passes C/R/E/D/U/I/V/P and DWG W: creation, a resize/recenter/scale/rotation transaction, canvas wires, seven rejection cases plus an atomic rollback, DWG reopen and re-edit, and three-step undo/redo. **W blocker (engine, pinned by a canary):** a DXF `DRAWINGVIEW` reopens as a different, opaque entity kind rather than as a ViewBorder, so only DWG restores the typed record. Not `Complete` until DXF loading restores the typed entity. Not covered: the linked view representation and drawing-view definition records. |
+| SectionSymbol | **Integration-tested / blocked at W by cadcodec (DXF SECTIONLINE)** | The earlier blocker was overstated, and reading cadcodec and OCS showed why. cadcodec documents `points` as the canonical geometry, says the point-count fields equal the point count in every verified ODA export, and ships `sync_display_fields()` to refresh the `end_a`/`end_b`/`tick_a`/`tick_b`/`label` projections; OCS's own grip and transform code already calls it. OCS also renders a symbol with no style and no view link. So the kind is mapped: writable `points` (each `{point, bulge, label, label_offset, raw_flag_280}`), `symbol_scale`, `style_handle` and `view_rep_handle`; read-only `view_symbol_version`, `raw_view_symbol_70`, `version`, `raw_flags_90`, the two derived counts and the five projections. The host sets `raw_point_count_90` and `raw_point_record_count` to the point count and calls `sync_display_fields()` whenever `points` is created or changed, and leaves a symbol whose points did not change exactly as read. Host validation requires at least two finite points with finite bulges and label offsets, a positive scale, and that each non-null reference is an existing `SectionViewStyle` (style) or `ViewRep` (view representation) class object; the wrong object kind is refused. Creating one without references gives a standalone symbol. `audit_python_section_symbol_lifecycle_over_real_ipc` (shared driver) passes C/R/E/D/U/I/V/P and DWG W: a two-point symbol, a three-point edit with a new label, bulge and scale in one transaction (counts and projections follow), canvas wires, seven rejection cases plus an atomic rollback, DWG reopen and re-edit, three-step undo/redo. `audit_python_section_symbol_references_over_real_ipc` covers valid references, a standalone symbol and four wrong-object refusals with host-made class objects. **W blocker (cadcodec, pinned by a canary; issue 5 in [cadcodec-reader-gaps.md](cadcodec-reader-gaps.md)):** the DXF reader dispatches `SECTIONLINE` only inside blocks, so a symbol in the drawing's entity list reopens as an `Unknown` entity. Open items that cannot be checked here: `raw_flags_90` has unknown semantics (0 for a new symbol, preserved on read), and whether AutoCAD accepts a symbol with no parent view. Scripts cannot create the style or view-representation objects. |
+| Light | **Integration-tested / blocked at W by acadrust (DXF `cast_shadows`)** | Writable: `name`, `light_type` (1 distant, 2 point, 3 spot), `position`, `target`, `status`, `light_color`, `plot_glyph`, `intensity`, the attenuation type and limits, `hotspot_angle`, `falloff_angle`, `cast_shadows`, `shadow_type`, `shadow_map_size`, `shadow_map_softness`, `photometric_mode`, `photometric_data`; `class_version` is read-only. Host validation requires a non-empty name, a known light type, finite placement, a spot or distant target that differs from the position, non-negative intensity, angles and limits, an attenuation start not above its end, a spot hotspot not above its falloff, and a non-negative shadow map size. `staged_python_light_lifecycle_over_real_ipc` (shared `run_mesh_lifecycle`) passes C/R/E/D/U/I/V/P and DWG W: a spot light with an RGB colour, an intensity/target/position/shadow transaction that preserves the colour and untouched fields, the canvas glyph, eight rejection cases plus an atomic rollback, DWG reopen and re-edit, and three-step undo/redo. **W blocker (engine, pinned by a canary):** the DXF reader does not restore `cast_shadows`, which reopens false; colour, placement and intensity persist. Not covered: photometric web data edits and sun/skylight objects. |
+| Region | **Complete (create from a profile + rigid move)** | New `SolidOperation::RegionFromProfile` and `doc.solids.region(profile, layer=None, delete_source=False)`. The host builds the region exactly as the REGION command does (`presspull_model::profile_geometry` then `cadkernel::brep::planar_region`), verifies it with `solid_to_sat`, puts it on `layer` or on the profile's layer, and erases the profile only when `delete_source` is set. One closed planar profile per call (a circle, ellipse, closed polyline, spline and so on); an open profile, a ray, a region, a missing entity or an empty layer is refused with a message before anything changes. Rigid moves go through the same `doc.solids.transform` channel as Solid3D. `audit_python_region_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P through the real runner: regions from a circle (source kept), a closed rectangle (source deleted) and a second circle on its own layer with exact extents, canvas geometry, six refusals that change nothing and record no undo step, a move with the exact shifted extent, DWG and DXF reopen with the payload lifting and the same extent, a reopened region moving again, and undo restoring the region exactly. Not covered: regions with holes and merging open curves into a boundary (the REGION command's second path), and AutoCAD acceptance of the payload. |
+| Body | **Integration-tested (rigid move only)** | Mapped read-only like Solid3D (same payload container). `audit_python_body_transform_over_real_ipc` moves a Body carrying a kernel box through `doc.solids.translate`, checks the exact extent, DWG reopen with a losslessly lifting payload and the exact volume, and the explanatory refusal of `create_entity('Body')`. Scripts cannot create a Body, and a non-solid (sheet or wire) body that does not lift is refused untouched. |
+| Solid3D | **Complete (create + rigid move)** | New in this session: an additive `HostApi::solid_operation` (`SolidOperation::Create` and `Transform`, plus a `SolidPrimitive` enum) carried by `PluginRequest::SolidOperation` / `PluginResponse::SolidResult` through both IPC clients, the server and `HostSession`, and a Python `doc.solids` API: `box`, `wedge`, `cylinder`, `sphere`, `torus`, `pyramid`, `transform`, `translate`, `rotate`, `mirror`. The host builds bodies with cadkernel, and every result goes through `solid_to_sat`, which lifts its own output back and refuses anything lossy. A transform first lifts the existing payload with `kernel_acis_body` and is refused, leaving the payload untouched, when that is lossy. Only rigid moves and mirrors are accepted (scaling and shear are refused). Regenerated `wires` follow the body, `silhouettes` are cleared and `history_handle` is dropped. Python sees `uid`, `point_of_reference` and `history_handle` read-only; `acis_data`, `wires` and `silhouettes` are excluded and preserved; creation through `create_entity` is refused with a message pointing at `doc.solids`. `audit_python_solid3d_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P through the real runner with the kernel as oracle: all six primitives match their analytic volumes (box, wedge and cube exactly, curved solids within 2 percent of the tessellated volume), a translate, a rotate and a mirror keep the volume and move the extent exactly and keep 12 edge wires, 13 refusals (zero and non-finite sizes, a torus with minor above major, too few pyramid sides, an empty layer, an unknown primitive, a wrong number count, a scaling matrix, a non-finite offset, a payload the kernel cannot lift, a missing entity) change nothing and leave no undo step, DWG and DXF reopen with the payload lifting losslessly and the same volume and extent, a reopened payload moves again, and undo restores the original solid exactly. Not covered: solids that carry parametric history, and AutoCAD acceptance of the written payload, which cannot be tested here. **Booleans** (`SolidOperation::Boolean`, `doc.solids.union`, `subtract` and `intersect`) are covered by `audit_python_boolean_lifecycle_over_real_ipc`: two overlapping boxes give exact volumes (union 360, subtract and intersect 120) and extents, the operands are consumed unless `keep_operands` (undo restores both exactly), a result takes the first operand's layer or an explicit one, a second planar operation chains on the result (a through-hole gives 104), eight refusals change nothing and record no undo step (same operand twice, a non-solid, a missing entity, an unliftable payload, an empty layer, an unknown operation, a disjoint intersection), and DWG and DXF reopen losslessly with a reopened result moving again. The kernel refuses many curved cases (measured in release: about 1 to 2 s when it succeeds, and `Coincident`, `CutRefused` or `NoClosedForm` when it does not, including a second cut in a drilled box); its reason reaches the script and nothing changes, shown by an `#[ignore]` curved test that takes about 27 s in a debug build. Booleans block the host thread and count against the script's 30 s budget; only Solid3D operands are accepted. |
+| Surface | **Complete (plane surface, extruded open profile, isolines, rigid move)** | New `SolidOperation::SurfaceFromProfile` and `SolidOperation::Extrude`, exposed as `doc.solids.surface(profile)` and `doc.solids.extrude(profile, direction)`. A closed planar profile becomes a `Plane` surface (built as the region body, so it keeps the plane kind); a profile extruded along a nonzero direction becomes a Solid3D when it is closed and a generic Surface when it is open, using OCS's own `extrusion_body`. Every payload is verified lossless by `solid_to_sat`, and rigid moves (now accepted for surfaces too) keep a plane a plane and turn any other kind generic, as OCS does after an edit. Python sees `surface_kind`, `modeler_format_version`, `point_of_reference` and `history_handle` read-only and `u_isolines` and `v_isolines` writable (0 to 200); the payload, wires, silhouettes and the kind-specific `surface_data` are excluded and preserved. The kind field is exposed as `surface_kind` because a bare `kind` key names the entity type in every Python dict; the new `exposed_property_names_are_unique_per_kind` test guards against that class of collision. `audit_python_surface_lifecycle_over_real_ipc` passes C/R/E/D/U/I/W/V/P through the real runner: two plane surfaces (one on its own layer), a surface from an open polyline extrusion, three extruded solids checked against their analytic volumes (a box exactly, curved ones within 2 percent), `delete_source` erasing only the intended profile, canvas geometry, nine refusals that change nothing and record no undo step, an isoline transaction with four rejections (500, negative, the read-only kind, an excluded key), moves with exact extents, DWG and DXF reopen with lifting payloads, matching extents, kept isolines and the plane kind, a reopened surface moving again, and exact undo. Not covered: lofted, revolved, swept and NURBS surfaces (a script cannot create them; an existing one is preserved and turns generic on a move), parametric history, and AutoCAD acceptance. |
+| Ole2Frame | **Complete** | Writable: `upper_left_corner`, `lower_right_corner`, `lock_aspect`, `is_paper_space`. Read-only: `version`, `source_application`, `ole_object_type`, `dwg_mode`. The embedded object `storage` and the frame `envelope` are opaque, excluded from the Python form, refused by the mutation check (`Ole2Frame embedded storage cannot change`) and preserved untouched. **Creation (new 2026-09-20):** `SolidOperation::EmbedPicture` and `doc.embed_picture(path, origin=(0, 0, 0), width=1, layer=None)` build a frame from a picture file with OCS's own `EmbeddedImage::from_file` and `build_embedded_ole`: PNG, JPEG and BMP are stored as read, any other format (a TIFF in the test) is re-encoded as PNG, `origin` is the bottom-left corner, `width` the frame width, and the height follows the picture's aspect. The generic `create_entity('Ole2Frame')` is refused with a message pointing at `doc.embed_picture`. Host validation requires finite corners spanning a nonzero size and `lock_aspect` of 0 or 1 for edits, and for creation a readable picture, a finite origin, a positive width and a non-empty layer. `audit_python_ole2frame_lifecycle_over_real_ipc` (shared driver) passes C/R/E/D/U/I/W/V/P through the real runner: creation from a PNG, a corner and aspect-lock transaction, canvas geometry, five rejection cases (including an attempt to write `storage`), an atomic rollback, **DWG and DXF reopen with the 119-byte embedded picture byte-for-byte intact (extracted through `extract_presentation`)**, re-edit, and three-step undo/redo. `audit_python_ole2frame_creation_rules_over_real_ipc` checks that PNG and JPEG are stored byte-for-byte, a TIFF becomes a PNG, the frame keeps the picture's 2:1 aspect with the requested origin and layer, and seven refusals (missing file, a non-image, empty layer, zero width, non-finite origin, a short origin list, and generic creation) change nothing and record no undo step. Not covered: OLE objects that are not pictures, and AutoCAD acceptance of the written frame, which cannot be tested here. |
+
+After each increment, update the row with test names, fixture paths, exact
+passing commands, the OCS commit hash, and any manual GUI result. Host and
+adapter changes now share the same repository commit. If a gate is untested,
+leave it pending. Do not raise the headline completion count from converter
+coverage alone.

docs/plugin-host-model.md

@@ -0,0 +1,137 @@
+# Scripting host model (API v7)
+
+This note describes how a script controls OCS and what the host guarantees. The
+per-kind evidence is in the [coverage ledger](plugin-host-model-coverage-ledger.md),
+the increment-by-increment record in the [completion plan](plugin-host-model-completion-plan.md),
+and the script-facing reference in `plugins/opencad-python/PLUGIN.md`. A reviewer new to
+the change should start with the [review guide](plugin-host-review-guide.md).
+
+## Shape
+
+Python runs in RustPython inside a separate plugin process
+(`plugins/opencad-python`), so a script cannot crash the editor. It talks to the
+host over the versioned IPC in `crates/ocs_plugin_api`. **The host owns the
+drawing**: it validates every request, records the undo step, refreshes scene
+caches and the shared document view, and marks the document dirty. The Python
+adapter is thin: it turns dictionaries into typed values and back, and holds no
+CAD rules of its own. Everything below is additive to API v7; a plugin built
+without it keeps working, and the default `HostApi` methods refuse.
+
+## What the host offers
+
+| Area | `HostApi` entry | What it does |
+|---|---|---|
+| Read | `document()`, `entity_snapshot` | The full `CadDocument` snapshot; a detached JSON view of any typed entity. |
+| Entities | `add_entity`, `remove_entity`, `update_entities_transaction` | Create, delete and replace entities. A transaction validates every replacement first and either commits all of them as one undo step or none. |
+| Selection | `selection`, `set_selection` | Ordered, tab-scoped, exact (missing or duplicate handles reject the request). |
+| Solids | `solid_operation` | Kernel-backed create, transform, booleans, extrude, region and surface from a profile, picture embedding. Every result is verified to lift back from its ACIS payload without loss; a refusal leaves the operands untouched. |
+| Tables | `table_operation` | Layers, text and dimension styles, blocks and their contents, linetypes, layouts (see below). |
+| Commands | `run_command` | Drives the real OCS command one step at a time (see below). |
+| Settings | `system_variable`, `set_system_variable` | `CLAYER`, `SNAPANG`, and a read-only `CTAB` (the current layout). |
+
+Entity kinds outside a generated schema still read (handle, kind, layer) and take
+`layer` changes; nothing is writable that the host has not validated.
+
+## Entity validation
+
+The host embeds a coverage catalog generated from its traced `EntityType`
+registry and `crates/ocs_plugin_api/entity_coverage_policy.json`. It classifies all
+48 variants: 43 canvas kinds, three internal records (`Block`, `BlockEnd`,
+`Seqend`) and two opaque fallbacks (`Extended`, `Unknown`), and records for each
+property its source field, type, shape, snapshot readability, Python access
+(`read_write`, `read_only`, `unmapped`) and validation status.
+
+Creation and edits are validated per kind (finite coordinates, positive radii and
+scales, unit directions, non-parallel vectors, in-range flags, reference targets
+that exist and have the right kind, and so on). Creation must be valid; an edit
+is refused only for problems it introduces, so already-invalid legacy values stay
+editable. Derived state is computed by the host, never trusted from a script (MLine
+geometry, Dimension measurement, Helix spline, Table merge dimensions, Spline
+rational flag, SectionSymbol counts, Viewport id and scale).
+
+Nested records are checked too. A dictionary for a vertex, edge or face may not
+carry an unknown key, and the fields that define its geometry are required
+(`entity_manifest.json`, `required_struct_fields`); a typo can no longer turn into
+a zero coordinate. Everything else in a nested record defaults when absent.
+
+Every kind is exercised through the real plugin runner by a per-kind audit that
+checks create, read, edit, delete, undo, invalid input with an atomic rollback,
+and a DWG and DXF round trip. A kind is `Complete` in the ledger only when all of
+those pass.
+
+## Tables
+
+`TableOperation` is one additive request with typed variants, executed by
+`HostSession::table_operation`. Every refusal is decided **before** the undo step is
+recorded, so a failure changes nothing and leaves the history alone.
+
+- **Layers:** create, modify, rename (entities follow), delete (refused while it
+  holds objects unless erasing them is asked for), set current. Layer `0`,
+  `Defpoints` and the current layer are protected.
+- **Text and dimension styles:** create, modify, rename, delete, set current. Dimension
+  style fields travel as a validated JSON object; handles, xref fields and the name are
+  host-managed. Renaming a text style updates the dimension styles that name it.
+  `Standard` and any style that is current or in use are protected.
+- **Blocks:** create from entities (copied in shifted by the base point, optionally
+  erasing the originals), modify, rename (inserts follow), delete (refused while
+  referenced), and add an entity to a definition through the normal validation path.
+  A block may not nest itself, directly or through other blocks.
+- **Linetypes:** simple dash, gap and dot patterns; rename follows layers and
+  entities; delete is refused while anything uses it.
+- **Layouts:** create with the default page setup and sheet viewport, rename, delete,
+  switch (through OCS's own layout switch), and page setup (paper size, rotation,
+  custom scale). `Model` is protected.
+
+Style and layout operations act on the active document, because they use the
+application's shared style and view machinery.
+
+## Commands
+
+`run_command` takes a `CommandRequest` (`Run`, `Start`, `Point`, `Text`, `Token`,
+`Entity`, `Selection`, `Enter`, `Cancel`) and answers with a `CommandOutcome`:
+whether the command is done or waiting, its prompt, what input it accepts, its
+keyword options, how many entities it added, tokens nobody asked for, and any
+error. It uses the same primitives as the automation channel and finishes each
+step synchronously on the host thread, so a step never waits for anything that has
+to arrive from outside; an earlier fire-and-forget replay could hang, this does not.
+
+Guards: refused while another command is active or off the active tab; refused for
+commands that could end the session or re-enter Python (`QUIT`, `EXIT`, `CLOSE*`,
+`NEW`, `QNEW`, `OPEN`, `SAVE*`, `RECOVER`, `SCRIPT`, `RUNSCRIPT`, `SCRIPTCOMMANDS`, `PY_*`); an editor or
+dialog a command opens is reported and closed by `Cancel`. The user can turn the whole
+facility off with the saved `SCRIPTCOMMANDS` preference (on by default; `SCRIPTCOMMANDS 0`
+at the command line): while it is off, every request except `Cancel` is refused (so a command a script left
+waiting can still be closed). A script cannot change
+it, because the runner refuses that command. The runner does not consult the automation
+on/off switch, which governs the external MCP and serve channels. The Python layer cancels
+any step sequence that leaves a command waiting.
+
+## Python surface
+
+`ocs.active_document` exposes `entities`, `create_entity`, `delete_entity`,
+`transaction`, `selection`, `solids`, `layers`, `text_styles`, `dim_styles`, `blocks`,
+`linetypes`, `layouts`, `command`, `start_command` and `modify` (offset, trim, extend,
+fillet, chamfer, move, copy, rotate, scale, mirror, erase, rectangular, polar, path and
+3-D arrays, explode, join, break, stretch, lengthen and polyline edits). `doc.coverage()`
+lists the catalog, and `doc.entities[handle].coverage` one entry, with the readable and
+editable keys and the fields the typed snapshot carries but the model does not map.
+
+Interactive picks use a token-based request and poll API because `PY_RUN` uses a
+fresh interpreter per invocation and a script cannot suspend while the user clicks.
+Drawing, selection and command notifications are kept in a bounded 256-event queue
+per tab between runs and drained with `doc.poll_events()`; an overflow is reported
+as `{"type": "overflow", "dropped": n}`. Tokens are bound to the tab that asked.
+
+## Known limits
+
+- Twelve of the 43 canvas kinds are not yet `Complete`; each has a named blocker in the
+  ledger. Seven are cadcodec DXF bugs whose fixes are submitted upstream but not yet adopted.
+- The DXF codec also drops some table properties (text style generation flags, block
+  descriptions, a dimension style's text-style name) and mis-scales one angle; these are
+  pinned by canaries and listed in `cadcodec-reader-gaps.md`.
+- Not available from a script: complex (text and shape) linetypes, plot devices and named
+  page setups, PEDIT's fit and spline options, and interactive-only commands such as HATCH.
+- A command step nests inside the editor's message handling. In a debug build a deep step
+  (PEDIT converting a line to a polyline) needs between 2 and 4 MiB of stack; the native
+  builds link with at least 8 MiB (16 MiB on Windows, `.cargo/config.toml`), the nesting depth
+  is fixed rather than recursive (`PY_*` is refused), and a release build uses far less.

docs/plugin-host-review-guide.md

@@ -0,0 +1,140 @@
+# Reviewer guide: scripting host model and the bundled Python plugin
+
+This is written for a reviewer who has not followed the work and may not have a Mac.
+It says what the change is, how to check it on Linux or Windows in a few minutes, where
+it touches existing code, what to read first, and what is deliberately left out.
+
+## What it is
+
+The bundled `opencad.python` plugin (RustPython, in its own process) can now control OCS
+through the versioned plugin API (v7), not only add lines and circles:
+
+- **Entities.** Create, read, edit, delete and undo for all 43 canvas kinds (41 creatable),
+  validated by the host, each with a DWG and DXF round-trip audit.
+- **Drawing tables.** Layers, text and dimension styles, blocks and their contents,
+  linetypes and layouts, and kernel-backed solids.
+- **Commands.** Scripts can run OCS's own commands step by step (offset, trim, fillet,
+  arrays, PEDIT and so on), with guards.
+
+**The host owns the drawing.** It validates every request, records the undo step and
+refuses without changing anything when it cannot honour a request. The Python adapter is a
+thin translation layer. The design and its guarantees are in
+[plugin-host-model.md](plugin-host-model.md).
+
+**Size.** 72 files, +30,705 / −178, against current `main`. About 15,000 added lines are the
+new plugin crate (including a 3,000-line lockfile and a generator), 5,600 are the API crate
+(3,500 of them the entity coverage validator), and 8,800 are in `src/`, of which roughly 6,200
+are tests in `plugin_host.rs`. Existing OCS code changes by **178 deleted lines in total** (151 of them outside docs, plugin and API);
+everything else is additive.
+
+## Check it without a Mac
+
+Nothing here needs macOS. The plugin tests are headless: they build the plugin and the
+application, then spawn the application as the plugin runner and talk to it over the real IPC.
+`stage-bundled.sh` already handles Linux (`.so`) and Windows (`.dll`), and the host looks for the
+plugin in `plugins/opencad.python/` next to the executable.
+
+```bash
+bash plugins/opencad-python/tools/stage-bundled.sh work/plugin --debug
+cargo build --bin OpenCADStudio
+OCS_TEST_PYTHON_PLUGIN=work/plugin/libopencad_python.so \
+OCS_PLUGIN_RUNNER_EXE=target/debug/OpenCADStudio \
+cargo test --lib -- --test-threads=1 python
+```
+
+(`opencad_python.dll` and `OpenCADStudio.exe` on Windows.) Expect 60 passed. **Without the two
+environment variables these tests are skipped and still report success**; `python-host-check.yml` fails
+instead of skipping.
+
+Already run for you:
+
+| Check | Where | Result |
+|---|---|---|
+| `python-host-check.yml` on the pull request | Linux and Windows | 115 plugin API tests, 20 plugin tests, 16 Python model tests, 60 host tests over real IPC, on each |
+| Release build with the plugin staged (a fork-only workflow, not in this PR) | Linux and Windows | 60 of 60 host tests on each; unsigned portable packages were produced and can be shared on request |
+| Local | macOS | the same, plus the wasm check |
+
+`main` now has its own `Tests` workflow (`cargo test --workspace --locked` on Linux), which will also run on
+this pull request. Run locally on macOS against the merged tree with the same command and `LC_ALL=C` and
+`--no-fail-fast`, the whole workspace gives **1,805 passed and 1 failed**. The one failure,
+`scene::text::lff::tests::fonts_parse_and_resolve`, also fails on pristine `main` in that environment (it
+needs font data) and is not part of this change; I expect it passes on the Linux runner but have not seen that.
+
+What has **not** been done: launching the GUI on Linux or Windows (the runners have no display), running the
+whole workspace suite on Windows, and building an AppImage or MSI that contains the plugin.
+
+## Reading order
+
+Read the contract first, then the host, then the adapter. The commits are in dependency order but
+several kinds and features are interleaved, so read by area rather than commit by commit.
+
+1. **The contract: `crates/ocs_plugin_api`.**
+   - `src/host.rs`: the new types and default-refusing methods: `SolidOperation`, `TableOperation`,
+     `CommandRequest` and `CommandOutcome`, `update_entities_transaction`, `selection`, `set_selection`,
+     `solid_operation`, `table_operation`, `run_command`.
+   - `src/ipc/**`: one additive request and response variant per method. The new variants are appended
+     after the existing ones so existing wire positions do not move. `v4/protocol.rs` has a bincode round-trip
+     test for each.
+   - `src/entity_coverage.rs`, `entity_coverage_policy.json`, `build.rs`: the per-kind validation and the
+     generated coverage catalog. This is the largest file and the most mechanical; the tests in it are the
+     rules in executable form.
+2. **The host: `src/app/plugin_host.rs`**, lines 1 to about 2,700 (the rest is tests). Sections in order:
+   scripted-entity normalization (host-derived state), solid operations, `table_operation` (layers, then
+   styles, blocks, linetypes, layouts), `run_command`, and the `HostApi` delegation at the end.
+3. **The adapter: `plugins/opencad-python`.** `entity_manifest.json` and `build/generate.rs` generate the
+   dict-to-entity conversions from the host's type registry; `src/ocs_module.rs` is the `ocs.*` bindings;
+   `src/document_model.py` is the script-facing document model; `PLUGIN.md` is the reference.
+4. **The small edits to existing OCS files** (this is where behaviour of existing code could change):
+
+   | File | Change |
+   |---|---|
+   | `src/plugin/external.rs`, `src/ui/window/plugin_manager.rs` | Bundled-plugin discovery (`bundled_plugins_dir`, `OCS_BUNDLED_PLUGINS_DIR`, a "Bundled with Open CAD Studio" label). A per-user plugin with the same id still overrides the bundled one. |
+   | `src/plugin/v4_support.rs`, `src/app/update/mod.rs`, `src/app/automation.rs` | New `DrawingChanged` and `CommandStateChanged` notifications; a drawing-changed notification after automation ops. |
+   | `src/entities/{mline,table,helix,dimension}.rs` | `normalize_scripted_*`: derived state a script must not set (MLine geometry, Table merges, Helix spline, Dimension measurement). Called only from the plugin host. |
+   | `src/scene/selection.rs`, `src/scene/entity.rs`, `src/app/layers.rs` | `replace_selection_exact`, preserving storage data on entity replacement, `set_current_layer_name`. |
+   | `src/app/style_ops.rs`, `src/app/control/mod.rs` | Four methods and one function widened to `pub(super)` so the host reuses OCS's own style rename, delete and in-use logic. |
+   | `src/app/settings.rs`, `src/app/mod.rs`, `src/app/update/file.rs`, `src/app/commands/styleprops.rs` | The `SCRIPTCOMMANDS` preference and command (see the decisions below). |
+   | `packaging/build_macos_signed.sh`, `.github/workflows/release.yml` | Stage (and, in the signed script, sign) the plugin in the macOS bundle; one added step in `release.yml`. |
+
+## What each area proves
+
+| Area | Evidence |
+|---|---|
+| 43 entity kinds | One real-IPC audit per kind (create, read, edit two properties, delete, undo and redo, invalid input with an atomic rollback, canvas geometry, DWG and DXF reopen and re-edit). [The ledger](plugin-host-model-coverage-ledger.md) records each kind's exact evidence or its blocker. |
+| Solids | Kernel primitives, moves, booleans, extrusions and regions, each verified to lift back from its ACIS payload; refusals leave operands untouched. |
+| Tables | `audit_python_layer_table`, `_text_and_dim_styles`, `_blocks`, `_block_contents`, `_linetypes_and_layouts`: dozens of refusals each, live and DWG and DXF persistence, one-step undo. |
+| Commands | `audit_python_modify_wrappers`: exact geometry for every wrapper (offset, trim, extend, fillet, chamfer, arrays, explode, join, break, stretch, lengthen, PEDIT edits), guards, an interactive session, undo. |
+| Nested input | `audit_python_nested_input_is_validated`: a mistyped vertex key or a missing location is refused instead of becoming a zero coordinate. |
+| Guardrail | `script_commands_setting_gates_the_runner` and a settings round-trip test. |
+
+## Decisions that are yours
+
+1. **`run_command` and the automation switch.** Script-driven commands do not consult the automation on/off
+   switch, which governs the external MCP and serve channels; a script is something the user chose to run. Say
+   if you would rather they respected it.
+2. **`SCRIPTCOMMANDS`.** A saved preference (on by default) toggled by a command turns script-driven commands off
+   entirely. It has no Options-page control; adding one needs locale and layout work outside this change.
+3. **Denylist.** A script cannot run `QUIT`, `EXIT`, `CLOSE*`, `NEW`, `QNEW`, `OPEN`, `SAVE*`, `RECOVER`,
+   `SCRIPT`, `RUNSCRIPT`, `SCRIPTCOMMANDS` or any `PY_*`, and only one command may be active. Tell me about any
+   other command that should be refused.
+4. **Nesting depth.** A command step runs inside the editor's message handling. It is not recursive, but a debug
+   build of one step (PEDIT converting a line to a polyline) needs 2 to 4 MiB of stack; the native builds link
+   with at least 8 MiB (16 MiB on Windows).
+5. **Splitting.** If 79 commits is too much, the natural seams are: the API and host core, the entity kinds,
+   the tables, and the command runner. Tell me and I will cut it that way.
+
+## What is deliberately not done
+
+- **Twelve of the 43 kinds are not `Complete`** (see the ledger). Seven are blocked by DXF bugs in
+  cadcodec, whose fixes are submitted as [cadcodec#48](https://github.com/HakanSeven12/cadcodec/pull/48) and
+  [#51](https://github.com/HakanSeven12/cadcodec/pull/51). **This change still pins the unfixed cadcodec revision**,
+  so its canary tests assert the old behaviour; once those merge, the pin moves, the canaries flip and those kinds
+  can be marked complete. The other five are held by the DWG format, a kind change on DXF save, an image-reactor
+  structure that cannot be verified, an update-only decision, and a missing creation path.
+- Not available from a script: complex (text and shape) linetypes, plot devices and named page setups, PEDIT's
+  fit and spline options, and interactive-only commands such as HATCH.
+- Two DXF gaps are not filed upstream because they need the exact XDATA layout AutoCAD expects (the TrueType
+  family name and the block description); they are listed in [cadcodec-reader-gaps.md](cadcodec-reader-gaps.md).
+- The AppImage, snap and MSI still ship without the plugin: `release.yml` stages it only in the macOS bundle
+  (one added step, part of this change). Bundling it for Linux and Windows means adding the same staging step
+  (`stage-bundled.sh`) to those jobs, which is small but I could not test the installers here.