changelog + SDK_DEFECTS: record that a Part holds one solid again (and what the multi-body notes now mean)

DECISION: say the change where a release reader and a maintainer look: the Unreleased changelog entry, and the
status lines of the defect log entries that were written for the multi-body research.

WHY - THE DISCUSSION (owner and assistant, 2026-11-10; full account in design-docs/part-holds-one-solid.md)
The editor needs several solids in one notebook with no assembly constraint (pattern a tool, then cut). The
multi-body Part was made for that and the owner judged it a wrong decision because it makes assembly hard; the
agreed analysis: those solids are notebook intermediates, not product items, so a Part is one solid and the editor
shows loose solids. The 2.2.8 release carrying the multi-body Part was withdrawn on 2026-11-10 after an audit
(connectors refused, explode_rassembly raised, the legacy scene compiler read part.body), so the next release's
notes must say that the feature is gone and what replaces it, and the defect log must not keep saying "worked
around by bodies".

- CHANGELOG.md, Unreleased / Changed: removed API (bodies=, Part.multi_body, part_shape,
  inspect_body_overlaps_rlist, BodyOverlapWarning, profile 3 / solid_cache.bodies), the reason, the open-solids
  rule (one open solid -> implicit Part; several -> SeveralOpenBodiesError; editor "N open solids" and
  use_as_product) and the remedy for deliverables of several solids (an Assembly of Parts).
- examples/SDK_DEFECTS.md entries 27-30 (marked [multi-solid research]): status lines updated: 27 (Compound drops
  tags) is still open but no product value is affected; 28 (pickling) names the new Part reader; 29 ("one solid per
  definition") is resolved, the `body:` id segment now only names the open solids of a preview; 30 (error guidance
  frozen by goldens): the guidance sentence is right again.

README.md and README.zh-CN.md were searched and say nothing about multi-body Parts, so they are unchanged.
sandbox/arm6 is untracked scratch work outside this worktree; it calls no `bodies=` (one comment mentions a
BodyOverlapWarning observation) and was left alone.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Ni Jingzhe
2026-11-10 04:08:51 +08:00
parent 01852ed1b9
commit d0040a7a7b
2 changed files with 21 additions and 9 deletions
+10
View File
@@ -6,6 +6,16 @@ user-facing notes live in [`docs/updates/`](docs/updates/) (English and
## Unreleased
### Changed
- A `Part` holds exactly one solid again. The multi-body Part of the withdrawn 2.2.8 release (`make_part_rpart(bodies=...)`,
`Part.multi_body`, `scad.part_shape`, `inspect_body_overlaps_rlist`, `BodyOverlapWarning`, part definition profile
`simplecad-part-definition-3` with `solid_cache.bodies`) is removed: a Part is the unit an assembly places, mates and gives
connectors to, and a Part of several bodies could do none of that (no connectors, `explode_rassembly` raised). Several
solids that exist side by side while a model is built (a tool next to its body) are ordinary notebook values: a part
notebook with one open solid still gets the implicit Part; with several there is no product and the run raises
`SeveralOpenBodiesError` naming them. The editor draws them side by side ("N open solids") and its `use_as_product`
makes the Part from the one you choose. Several solids as a deliverable are one Part each in an Assembly.
## 2.2.8 — 2026-11-09
User-facing notes: [`docs/updates/2.2.8.md`](docs/updates/2.2.8.md).
+11 -9
View File
@@ -421,9 +421,8 @@ that surfaced it is in brackets.
- **Root cause:** a Compound is a new shape root with its own entity registry;
the semantic state of the input roots is not carried over, and the copy
helper only works within one root.
- **Status:** open. Multi-body parts keep their bodies as separate Solid roots
(`Part.bodies`), so they are not affected; `product.bodies.part_shape`
documents that its Compound is a geometry view without tags.
- **Status:** open. The multi-body Part that made this matter was withdrawn (a Part holds one Solid), so no
product value is affected any more; a user-built Compound still drops tags.
- **Fix direction:** either carry tags into a Compound built from tagged
roots (sub-shapes are shared, so the mapping is exact), or refuse
`_copy_semantic_state_from` across roots instead of doing nothing.
@@ -437,7 +436,8 @@ that surfaced it is in brackets.
- **Root cause:** `_glue/values.py` parses the parameter names out of the
pybind11 `__init__` docstring and reads each back with `getattr`.
- **Status:** worked around: `_ARGUMENTS` maps a class to per-parameter
readers (Part: `body`/`bodies`).
readers (Part: `body`, which is the `Body` when the body carries a name or an appearance; the `bodies`
argument went with the multi-body Part).
- **Fix direction:** give the C++ values an explicit `__getstate__`/
`py::pickle` (as `ql` selectors have) instead of docstring parsing.
@@ -450,17 +450,19 @@ that surfaced it is in brackets.
- **Trigger:** any part with more than one solid.
- **Root cause:** "is a part" and "has one solid" were the same fact until
now.
- **Status:** worked around: bodies get an id segment `body:<body_id>`
(`entity/<part>/body:<id>/...`, `node/<part>/body:<id>`), one-body parts
keep their old ids byte for byte; the kind stays `single_solid`.
- **Status:** resolved by withdrawing the multi-body Part: a Part is one solid again, so `single_solid` is
accurate. The `body:<name>` id segment (`entity/<notebook id>/body:<name>/...`, `node/<notebook id>/body:<name>`)
remains only for the open solids of a notebook that has no Part yet (a preview of loose solids); Part ids
are the old ones byte for byte.
- **Fix direction:** treat `single_solid` as the name of the part kind (rename
at the next package schema bump) and keep the `body:` segment the only
way to address a body.
## 30. Error guidance is frozen by parity goldens [multi-solid research]
- **Symptom:** the `make_part_rpart` guidance still says "Union intended multiple bodies into one Solid before
creating the Part.", which is wrong now that `bodies=` exists; changing it fails
- **Symptom:** the `make_part_rpart` guidance says "Union intended multiple bodies into one Solid before
creating the Part." (it was wrong while `bodies=` existed, and is right again now that a Part holds one solid; it
does not mention the Assembly alternative). Changing it fails
`src/cpp/tests/python/test_product_values.py::test_part_creation_and_errors`.
- **Root cause:** the C++ port compares every error's `what_happened` / `possible_causes` / `how_to_fix` with goldens
captured from the old Python SDK (`tests/golden/product_*.json`), so guidance cannot follow the API.