release: 2.2.7

CHANGELOG.md

@@ -6,6 +6,8 @@ user-facing notes live in [`docs/updates/`](docs/updates/) (English and
 
 ## Unreleased
 
+## 2.2.7 — 2026-10-30
+
 ### Fixed
 - The editor starts with whatever model file is on disk: a model kept by an older build that leaves parts out, or a damaged
   one, is not restored (and no longer stops the kernel from starting, which showed as "starting the kernel" for ever), and

README.md

@@ -149,20 +149,22 @@ the full crank cycle sweeps clean in the same sim ·
 
 ---
 
-## Update Notes (2.2.7b1)
+## Update Notes (2.2.7)
 
 > Validate generated definitions, assembly constraints, and manufacturing
 > geometry before production use.
 
-- **The geometry engine is C++ on OpenCASCADE, inside the wheel.** `pip install simplecadapi` needs no
-  `cadquery-ocp`; the public API and the previous test suite are unchanged.
-- **Prebuilt wheels** for Linux x86_64 and aarch64, macOS arm64 (14+) and Windows x86_64, Python 3.10-3.13,
-  all on the same OpenCASCADE 7.9.3. This is a beta: the first release with prebuilt wheels.
-- **Faster and smaller.** On the six-axis arm: cold build 43.8 s to 29.1 s, rebuild with nothing changed
-  12.8 s to 6.0 s, `import simplecadapi` 1.6 s / 360 MB to 0.2 s / 68 MB.
-- **Errors are English** and the tag and query errors render in full, like operator errors.
-
-Full notes for this version: [`docs/updates/2.2.7b1.md`](docs/updates/2.2.7b1.md).
+- **First stable release of the C++ engine**, inside prebuilt wheels (Linux x86_64 and aarch64, macOS arm64 14+, Windows
+  x86_64; Python 3.10-3.13; one OpenCASCADE 7.9.3). `pip install simplecadapi` needs no `cadquery-ocp`.
+- **The editor is faster.** On the six-axis arm a joint angle never seen before takes 2.7 s (was 5.7 s in the beta), one seen
+  before 0.6 s (was 5.5 s), and the model reaches the page 0.36-0.41 s after the last cell. The kernel uses about 300 MB more
+  memory at idle than the beta.
+- **`Var` and `Expr` behave like numbers**: `r > 3`, `int(r)`, `round(r, 2)`, `range(n)`, `max(r, 3)`, f-strings work, and
+  a ql predicate with a value computed from a `Var` matches. `bool(var)` and `json.dumps(var)` still raise.
+- **`shape.wrapped` is an OCP shape** when OCP is installed (`simplecadapi[verify]`), a copy, so OCCT verifier scripts run as written.
+- Failing fillets, chamfers and ql selections attach their picture again. Notebooks with saved parameter values rebuild once.
+
+Full notes for this version: [`docs/updates/2.2.7.md`](docs/updates/2.2.7.md).
 Earlier versions: the [changelog](CHANGELOG.md) and [`docs/updates/`](docs/updates/).
 
 ---
@@ -183,7 +185,7 @@ in a compact public API for creating solids, applying features, tagging semantic
 intent, querying topology, exporting manufacturing files, and translating recorded
 models into FreeCAD workflows.
 
-Current release: `simplecadapi==2.2.7b1`.
+Current release: `simplecadapi==2.2.7`.
 
 ## What It Provides
 
@@ -664,6 +666,7 @@ and the [STEP reconstruction workflow](docs/skill/references/workflows/step-reco
 
 ## Documentation
 
+- 2.2.7 update notes: [`docs/updates/2.2.7.md`](docs/updates/2.2.7.md)
 - 2.2.7b1 update notes: [`docs/updates/2.2.7b1.md`](docs/updates/2.2.7b1.md)
 - 2.2.6.post2 update notes: [`docs/updates/2.2.6.post2.md`](docs/updates/2.2.6.post2.md)
 - 2.2.6.post1 update notes: [`docs/updates/2.2.6.post1.md`](docs/updates/2.2.6.post1.md)

README.zh-CN.md

@@ -133,19 +133,20 @@ CalculiX 静力 FEM（边界面按保真的 `interface.*` 标签选取，仿真
 
 ---
 
-## 更新日志（2.2.7b1）
+## 更新日志（2.2.7）
 
 > 投入生产前请验证生成的定义、装配约束和制造几何。
 
-- **几何引擎改为基于 OpenCASCADE 的 C++，随 wheel 发布。** `pip install simplecadapi` 不再需要 `cadquery-ocp`；
-  公开 API 和此前的整套测试不变。
-- **预编译 wheel**：Linux x86_64 与 aarch64、macOS arm64（14+）、Windows x86_64，Python 3.10-3.13，
-  全部使用同一份 OpenCASCADE 7.9.3。这是 beta，也是第一个带预编译 wheel 的版本。
-- **更快、更小。** 六轴机械臂：冷构建 43.8 s 到 29.1 s，无改动重建 12.8 s 到 6.0 s，
-  `import simplecadapi` 1.6 s / 360 MB 到 0.2 s / 68 MB。
-- **报错全部为英文**，标签与查询类报错和算子报错一样完整渲染。
+- **C++ 引擎的第一个正式版**，随预编译 wheel 发布（Linux x86_64 与 aarch64、macOS arm64 14+、Windows x86_64；
+  Python 3.10-3.13；统一使用 OpenCASCADE 7.9.3）。`pip install simplecadapi` 不再需要 `cadquery-ocp`。
+- **编辑器更快。** 六轴机械臂上一个没见过的关节角 2.7 s（beta 是 5.7 s），见过的 0.6 s（beta 是 5.5 s），
+  模型在最后一个 cell 之后 0.36-0.41 s 到达页面。内核空闲时比 beta 多用约 300 MB 内存。
+- **`Var` 和 `Expr` 像数字一样工作**：`r > 3`、`int(r)`、`round(r, 2)`、`range(n)`、`max(r, 3)`、f-string 可用，
+  用 `Var` 算出的值写 ql 谓词也能匹配。`bool(var)` 和 `json.dumps(var)` 仍然报错。
+- **装了 OCP 时 `shape.wrapped` 是 OCP 形状**（`simplecadapi[verify]`），是拷贝，OCCT 验证脚本可以原样运行。
+- fillet、chamfer 和 ql 选择失败重新附带图片。保存了参数值的笔记本会重建一次。
 
-本版本的完整说明：[`docs/updates/2.2.7b1.zh-CN.md`](docs/updates/2.2.7b1.zh-CN.md)。
+本版本的完整说明：[`docs/updates/2.2.7.zh-CN.md`](docs/updates/2.2.7.zh-CN.md)。
 更早的版本：见[更新日志](CHANGELOG.md)和 [`docs/updates/`](docs/updates/)。
 
 ---
@@ -163,7 +164,7 @@ CalculiX 静力 FEM（边界面按保真的 `interface.*` 标签选取，仿真
 
 SimpleCADAPI 是一个基于 OCP 的 Python CAD SDK，提供清晰的函数式建模操作和可重放的模型图。它在 OpenCascade 几何内核之上提供精简的公共 API，可用于创建实体、应用特征、添加语义标签、查询拓扑、导出制造文件，以及将记录的模型转换为 FreeCAD 工作流。
 
-当前版本：`simplecadapi==2.2.7b1`。
+当前版本：`simplecadapi==2.2.7`。
 
 ## 核心能力
 
@@ -558,6 +559,7 @@ uv run --extra gmsh python examples/ap242_gmsh_volume_mesh/export_fem_mesh.py
 
 ## 文档
 
+- 2.2.7 更新说明：[`docs/updates/2.2.7.zh-CN.md`](docs/updates/2.2.7.zh-CN.md)
 - 2.2.7b1 更新说明：[`docs/updates/2.2.7b1.zh-CN.md`](docs/updates/2.2.7b1.zh-CN.md)
 - 2.2.6.post2 更新说明：[`docs/updates/2.2.6.post2.zh-CN.md`](docs/updates/2.2.6.post2.zh-CN.md)
 - 2.2.6.post1 更新说明：[`docs/updates/2.2.6.post1.zh-CN.md`](docs/updates/2.2.6.post1.zh-CN.md)

docs/skill/SKILL.md

@@ -4,9 +4,9 @@ description: Build, assemble, inspect, reconstruct, and export parametric CAD mo
 license: Apache-2.0
 metadata:
   project: simplecadapi
-  version: 2.2.7b1
+  version: 2.2.7
   package-name: simplecadapi
-  package-version: 2.2.7b1
+  package-version: 2.2.7
 ---
 
 # SimpleCAD SDK Skill

docs/updates/2.2.7.md

@@ -0,0 +1,77 @@
+# 2.2.7 Update Notes
+
+The first stable release of the C++ engine (2.2.7b1 was the beta): the geometry engine is C++ on OpenCASCADE, shipped inside
+prebuilt wheels, and `pip install simplecadapi` needs no `cadquery-ocp` and no OpenCASCADE on the machine. This release makes
+the editor much faster, lets `Var` and `Expr` be used like numbers, and fixes what the beta left out.
+
+## Prebuilt packages
+
+Linux x86_64 and aarch64 (manylinux_2_28), macOS arm64 (14+) and Windows x86_64, each for Python 3.10, 3.11, 3.12 and 3.13, all
+linked against the same OpenCASCADE 7.9.3. There are no wheels for macOS Intel, musl Linux or Windows on ARM; there the source
+distribution builds the module and needs a C++20 toolchain and OpenCASCADE >= 7.8.
+
+## The editor is faster
+
+Measured on the six-axis arm (`sandbox-envs/desktop_arm_sources`) in the editor, same machine:
+
+| | 2.2.6.post2 | 2.2.7b1 | 2.2.7 |
+|---|---|---|---|
+| cold start | 64.5 s | 48.8 s | 34.9 s |
+| start with nothing changed | 4.1 s | 2.1 s | 1.6 s |
+| a joint angle never seen before | 4.4 s | 5.7 s | 2.7 s |
+| a joint angle seen before | 6.2 s | 5.5 s | 0.6 s |
+| idle memory | 1038 MB | 322 MB | 617 MB |
+
+* **The model reaches the page sooner.** The kernel publishes the model as parts identified by the content of their geometry,
+  the server sends each page only the parts that page lacks, and the page builds geometry only for new parts. A joint angle
+  moves 115 KB instead of 6.26 MB; from the last cell to the model on screen takes 0.36-0.41 s instead of 1.3-3.2 s. The
+  model is pushed over the WebSocket in the `preview` event itself, with no second request.
+* **The kernel keeps what its cells made** and what `use()` returned, and a saved parameter's digest follows what a cell
+  reads: changing one joint angle no longer redoes the cell that builds the parts. The cost is memory: about 300 MB more at
+  idle than the beta (the kernel keeps the twelve most recent cell results).
+* One case is still slower than 2.2.6: a new value of `OPEN_STROKE` on the arm takes 5.8 s (2.2.6.post2: 4.7 s; the beta:
+  6.8 s), because the assembly solve it triggers is real work.
+
+## `Var` and `Expr` behave like numbers
+
+`int(r)`, `round(r, 2)`, `r > 3`, `max(r, 3)`, `sorted([...])`, `range(n)`, `[0] * n`, `lst[n - 1]`, `r // 2`, `r % 3`,
+`f"{r:.2f}"` and `str(r)` now work and read the value the variable has now; arithmetic still builds the formula that keeps
+the link to the parameters. `r == 5.0` is `True` (it was `False`), and a ql predicate with a value computed from a `Var`
+(`ql.prop("geom.length", ">=", 2 * math.pi * radius)`) now matches, where 2.2.6 matched nothing.
+Still errors: `bool(var)` (write `if r > 0:`) and `json.dumps(var)`; numpy needs `float(var)`. A notebook that relies on the new
+behaviour does not run unchanged on 2.2.6; `float(var)` makes it portable.
+
+## `shape.wrapped` is an OCP shape
+
+With OCP installed (`pip install "simplecadapi[verify]"`), `shape.wrapped` is an OCP shape of the class of its kind
+(`TopoDS_Solid`, `TopoDS_Face`, ...), so verifier scripts written with the OCCT API run as written. It is a copy: every access
+makes a new one, and a change made to it does not reach the SDK's shape. `simplecadapi.verify.to_ocp` / `from_ocp` are the
+explicit forms. `SCA_WRAPPED=native|ocp` chooses. Without OCP it stays the SDK's own OCCT shape. The `fem` extra is gone.
+
+## Failures and fixes
+
+* A failing fillet or chamfer, and a failing ql `exactly()`, attach their picture again (2.2.7b1 drew one for booleans only).
+* The editor starts with whatever model file is on disk: a damaged or partial one is not restored and no longer leaves the
+  editor "starting the kernel" for ever. A damaged preview is refused with the reason (`400`), not as missing parts.
+* Cache entries written by an older build that name classes which no longer exist are replaced; a notebook with such entries
+  (a child run through `use`, the arm's gripper) takes 0.8 s instead of 3-6 s.
+* An OCCT failure while reading a geometry type or closedness makes the property absent, as in 2.2.6.
+* A failure that is handled and used to leave no trace prints a `[sca]` line on stderr.
+
+## Upgrading
+
+* **Notebooks with saved parameter values rebuild once** after the upgrade (their cells' digests changed).
+* `shape.wrapped` is a copy when OCP is installed (above).
+* New switches are listed in `docs/environment.md`.
+
+## The skill
+
+`discipline/notebook-cell-design.md` states where the cell boundaries go, when a number is a `scad.var`, and why, with the error
+you get when a rule is broken.
+
+## For contributors
+
+The C++ tree is formatted (`.clang-format`, checked in CI), has a `CONTRIBUTING.md`, a reading order and a landing plan under
+`src/cpp/`, named tolerances (`scad::tol`), no swallowed exceptions or unchecked optionals that clang-tidy reports, and its
+doctest executables run in CI in Release and under ASan and UBSan. The old tests that do not apply to the soft renderer are
+listed in `src/cpp/docs/DEVIATIONS.md`.

docs/updates/2.2.7.zh-CN.md

@@ -0,0 +1,72 @@
+# 2.2.7 更新说明
+
+C++ 引擎的第一个正式版（2.2.7b1 是 beta）：几何引擎是基于 OpenCASCADE 的 C++，随预编译 wheel 一起发布，
+`pip install simplecadapi` 不再需要 `cadquery-ocp`，机器上也不需要装 OpenCASCADE。这一版让编辑器快了很多，让 `Var` 和 `Expr`
+可以像数字一样使用，并补上了 beta 遗漏的东西。
+
+## 预编译包
+
+Linux x86_64 与 aarch64（manylinux_2_28）、macOS arm64（14+）、Windows x86_64，各支持 Python 3.10、3.11、3.12、3.13，
+全部链接同一份 OpenCASCADE 7.9.3。macOS Intel、musl Linux、Windows ARM 没有预编译包；这些平台由源码包现场构建，
+需要 C++20 工具链和 OpenCASCADE >= 7.8。
+
+## 编辑器更快
+
+六轴机械臂（`sandbox-envs/desktop_arm_sources`）在编辑器中的实测，同一台机器：
+
+| | 2.2.6.post2 | 2.2.7b1 | 2.2.7 |
+|---|---|---|---|
+| 冷启动 | 64.5 s | 48.8 s | 34.9 s |
+| 无改动启动 | 4.1 s | 2.1 s | 1.6 s |
+| 一个没见过的关节角 | 4.4 s | 5.7 s | 2.7 s |
+| 一个见过的关节角 | 6.2 s | 5.5 s | 0.6 s |
+| 空闲内存 | 1038 MB | 322 MB | 617 MB |
+
+* **模型更快到达页面。** 内核把模型发布成按几何内容标识的零件，服务器只给每个页面发它缺的零件，页面只为新零件建几何。
+  改一个关节角只传 115 KB（原来 6.26 MB）；从最后一个 cell 到模型显示在屏幕上是 0.36-0.41 s（原来 1.3-3.2 s）。
+  模型随 `preview` 事件直接经 WebSocket 推送，不再有第二次请求。
+* **内核会记住 cell 的结果**和 `use()` 的返回值，保存的参数值的摘要只跟随 cell 真正读到的参数：改一个关节角不会再重做建零件的 cell。
+  代价是内存：空闲时比 beta 多约 300 MB（内核保留最近的 12 个 cell 结果）。
+* 仍有一个场景比 2.2.6 慢：机械臂上一个新的 `OPEN_STROKE` 值要 5.8 s（2.2.6.post2 是 4.7 s；beta 是 6.8 s），
+  因为它触发的装配求解是真实的计算。
+
+## `Var` 和 `Expr` 像数字一样工作
+
+`int(r)`、`round(r, 2)`、`r > 3`、`max(r, 3)`、`sorted([...])`、`range(n)`、`[0] * n`、`lst[n - 1]`、`r // 2`、`r % 3`、
+`f"{r:.2f}"`、`str(r)` 现在都可用，读取变量当前的值；算术运算仍然生成保留参数联系的公式。`r == 5.0` 为 `True`（原来是 `False`），
+用 `Var` 算出来的值写 ql 谓词（`ql.prop("geom.length", ">=", 2 * math.pi * radius)`）现在能匹配，2.2.6 里匹配不到任何东西。
+仍然报错的：`bool(var)`（请写 `if r > 0:`）和 `json.dumps(var)`；numpy 需要 `float(var)`。依赖新行为的笔记本不能原样在 2.2.6 上运行，
+用 `float(var)` 可以保持可移植。
+
+## `shape.wrapped` 是 OCP 形状
+
+装了 OCP（`pip install "simplecadapi[verify]"`）时，`shape.wrapped` 是对应类别的 OCP 形状（`TopoDS_Solid`、`TopoDS_Face` 等），
+用 OCCT API 写的验证脚本可以原样运行。它是一份拷贝：每次访问都生成新的，对它的修改不会影响 SDK 的形状。
+`simplecadapi.verify.to_ocp` / `from_ocp` 是显式写法。`SCA_WRAPPED=native|ocp` 可以选择。没装 OCP 时仍是 SDK 自己的 OCCT 形状。
+`fem` extra 已移除。
+
+## 失败信息与修复
+
+* fillet / chamfer 失败和 ql 的 `exactly()` 失败重新附带图片（2.2.7b1 只有布尔运算有）。
+* 编辑器用磁盘上现有的模型文件启动：损坏或不完整的文件不会被恢复，也不会再让编辑器一直停在"starting the kernel"。
+  损坏的预览会带着原因被拒绝（`400`），不再被当成缺零件。
+* 旧版本写入的、指向已不存在的类的缓存条目会被替换；有这类条目的笔记本（通过 `use` 运行的子笔记本、机械臂的夹爪）
+  耗时从 3-6 s 降到 0.8 s。
+* 读取几何类型或封闭性时发生的 OCCT 失败会让该属性为"无"，与 2.2.6 一致。
+* 过去被处理但不留痕迹的失败，现在会在 stderr 打印一行 `[sca]`。
+
+## 升级须知
+
+* **保存了参数值的笔记本在升级后会重建一次**（它们的 cell 摘要变了）。
+* 装了 OCP 时 `shape.wrapped` 是拷贝（见上）。
+* 新增的开关见 `docs/environment.md`。
+
+## Skill
+
+`discipline/notebook-cell-design.md` 规定了 cell 边界放在哪里、什么时候一个数应当是 `scad.var`，以及原因，并给出违反规则时会看到的报错。
+
+## 面向贡献者
+
+C++ 代码已统一格式（`.clang-format`，CI 检查），有 `CONTRIBUTING.md`、阅读顺序和合入计划（在 `src/cpp/` 下），容差有了名字（`scad::tol`），
+clang-tidy 不再报告被吞掉的异常和未检查的 optional，doctest 可执行文件在 CI 中以 Release 以及 ASan、UBSan 运行。
+不适用于软渲染器的旧测试列在 `src/cpp/docs/DEVIATIONS.md` 里。

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simplecadapi"
-version = "2.2.7b1"
+version = "2.2.7"
 description = "A simplified OpenCASCADE-native CAD modeling Python API"
 readme = "README.md"
 license = { file = "LICENSE" }