simplecadapi 2.0.7__tar.gz → 2.0.9__tar.gz

{simplecadapi-2.0.7 → simplecadapi-2.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simplecadapi
-Version: 2.0.7
+Version: 2.0.9
 Summary: A simplified CAD modeling Python API based on CADQuery
 Project-URL: Homepage, https://github.com/NiJingzhe/SimpleCADAPI
 Project-URL: Repository, https://github.com/NiJingzhe/SimpleCADAPI
@@ -385,7 +385,7 @@ Experimental scripts and temporary modeling examples are not included as formal
 
 ## Package Installation (Python Package Managers)
 
-Current package name: `simplecadapi`, version: `2.0.7` (see `pyproject.toml`).
+Current package name: `simplecadapi`, version: `2.0.9` (see `pyproject.toml`).
 
 ### Method A: Install from package repository with pip
 
@@ -418,7 +418,7 @@ uv add simplecadapi
 The repository already contains example build artifacts (`dist/`):
 
 ```bash
-pip install dist/simplecadapi-2.0.7-py3-none-any.whl
+pip install dist/simplecadapi-2.0.9-py3-none-any.whl
 ```
 
 If you need to rebuild:

{simplecadapi-2.0.7 → simplecadapi-2.0.9}/README.md

@@ -9,7 +9,7 @@ Experimental scripts and temporary modeling examples are not included as formal
 
 ## Package Installation (Python Package Managers)
 
-Current package name: `simplecadapi`, version: `2.0.7` (see `pyproject.toml`).
+Current package name: `simplecadapi`, version: `2.0.9` (see `pyproject.toml`).
 
 ### Method A: Install from package repository with pip
 
@@ -42,7 +42,7 @@ uv add simplecadapi
 The repository already contains example build artifacts (`dist/`):
 
 ```bash
-pip install dist/simplecadapi-2.0.7-py3-none-any.whl
+pip install dist/simplecadapi-2.0.9-py3-none-any.whl
 ```
 
 If you need to rebuild:

{simplecadapi-2.0.7 → simplecadapi-2.0.9}/docs/api/union_rsolidlist.md

@@ -3,7 +3,12 @@
 ## API Definition
 
 ```python
-def union_rsolidlist(*solids: Union[Solid, Sequence[Solid]]) -> List[Solid]
+def union_rsolidlist(
+    *solids: Union[Solid, Sequence[Solid]],
+    clean: bool = True,
+    glue: bool = True,
+    tol: Optional[float] = None,
+) -> List[Solid]
 ```
 
 *Source: operations.py*
@@ -15,13 +20,18 @@ Compute the boolean union of one or more solids.
 All boolean operations (union/cut/intersect) accept a mix of Solid and
 sequences; results are always returned as a list of Solid.
 Keep the list result unless you have explicitly verified `len(result) == 1`.
+SimpleCAD enables glue mode by default and applies a conservative internal fuzzy
+tolerance, so normal modeling code does not need to tune boolean parameters.
+By default this follows CadQuery's union flow: perform one OCC fuse across the
+input solids, then call `clean()` to unify same-domain faces when possible.
 Touching-but-not-intersecting inputs can legitimately return multiple solids.
 If that happens, keep using the list: pass it directly into later union calls,
 or iterate over the solids for later cut/intersect steps.
+When the returned solids are still separated by more than the active tolerance,
+SimpleCAD prints a stdout warning explaining that the objects do not touch and
+that their gap exceeds `tol`.
 If you truly need exactly one merged solid, you must check the list length
-before using `result[0]`. When the length is not 1, do not pick an element
-arbitrarily; instead, adjust part placement so the solids overlap slightly,
-then run the union again.
+before using `result[0]`.
 
 ## Parameters
 
@@ -29,6 +39,18 @@ then run the union again.
 
 - **Description**: One or more Solid objects or sequences of Solid. Nested sequences are flattened before processing.
 
+### clean
+
+- **Description**: Call CadQuery's `clean()` after the union to remove splitter edges and unify same-domain faces when possible.
+
+### glue
+
+- **Description**: Enable OCC glue mode for touching or partially overlapping inputs. Defaults to `True` for SimpleCAD's standard union behavior.
+
+### tol
+
+- **Description**: Optional fuzzy-boolean tolerance passed to the OCC union kernel. When omitted, SimpleCAD derives a conservative scale-aware value automatically.
+
 ## Returns
 
 List[Solid]: Resulting solids after union attempts. Solids that can be fused

simplecadapi-2.0.9/paper_section.tex

@@ -0,0 +1,92 @@
+\subsection{ECIP-Compliant CAD API Design}
+
+\DP{ECIP (referred to as $\mathtt{SimpleCADAPI}$ in the actual project) is designed as a \JZ{command while functional programming style} Python API built on top of CadQuery's $\mathtt{occ\_impl.shapes}$ module. It serves as an LLM-friendly intermediate representation that remains semantically aligned with CadQuery. The geometric classes (e.g., \texttt{Vertex}, \texttt{Edge}, \texttt{Solid}) are implemented as lightweight wrappers over CadQuery objects, preserving full interoperability with native CadQuery operations.} 
+
+\DP{The design follows the Open-Closed Principle: core geometric types are closed for modification, while operations and extensions are introduced through additional functions. Moreover, SimpleCADAPI is fully compatible with the NumPy library, enabling efficient mathematical computation and geometric transformation directly on CAD entities. It provides explicit input-output interfaces for each operation, facilitating LLM-driven code generation, iterative correction, and modular composition, while retaining the high-level modeling capabilities of CadQuery. SimpleCADAPI is organized into two main parts: the \textbf{Core} module and the \textbf{API} module.}
+
+\subsubsection{Core Module}
+\FFX{The Core module encapsulates fundamental geometric types and primitive operations. By wrapping the underlying OpenCASCADE \(\mathtt{TopoDS\_Shape}\) classes, it establishes a clear hierarchy and semantic structure for geometric objects, while also managing coordinate systems, supporting tagging and metadata attachment, and enforcing strict type annotations and exception handling.}
+\begin{table*}[t]
+\centering
+\caption{Summary of core CAD modeling functions by category}
+\label{tab:core_functions}
+\begin{tabular*}{\textwidth}{@{\extracolsep{\fill}}lcc@{}}
+\toprule
+\textbf{Category} & \textbf{Examples} & \textbf{Count} \\
+\midrule
+Creation & \mcode{make\_box\_rsolid}, \mcode{make\_cylinder\_rsolid}, \mcode{make\_circle\_rwire} & 25 \\
+Transformation & \mcode{translate\_shape}, \mcode{rotate\_shape}, \mcode{mirror\_shape} & 3 \\
+3D Operations & \mcode{extrude\_rsolid}, \mcode{revolve\_rsolid}, \mcode{loft\_rsolid}, \mcode{sweep\_rsolid} & 4 \\
+Boolean & \mcode{union\_rsolidlist}, \mcode{cut\_rsolidlist}, \mcode{intersect\_rsolidlist} & 3 \\
+Advanced Features & \mcode{fillet\_rsolid}, \mcode{chamfer\_rsolid}, \mcode{shell\_rsolid}, \mcode{helical\_sweep\_rsolid} & 4 \\
+Pattern & \mcode{linear\_pattern\_rsolidlist}, \mcode{radial\_pattern\_rsolidlist} & 2 \\
+Metadata, Tagging, \& Selection & \mcode{set\_tag}, \mcode{ql.tag}, \mcode{ql.meta}, \mcode{ql.where}, \mcode{ql.order\_by} & 14 \\
+Export & \mcode{export\_step}, \mcode{export\_stl} & 2 \\
+\bottomrule
+\end{tabular*}
+\end{table*}
+\begin{itemize}
+    \item \textbf{\FFX{Geometric Object Hierarchy:}} \FFX{The Core module defines a layered geometric object model comprising the following primary classes, all inheriting from \(\mathtt{TaggedMixin}\) to provide unified tagging and metadata management:}
+    \begin{enumerate}[label=\textbf{(\arabic*)}]
+        \item \textbf{\FFX{Vertex}}: \FFX{0-dimensional points in 3D space.}
+        \item \textbf{\FFX{Edge}}: \FFX{1-dimensional curves connecting vertices.}
+        \item \textbf{\FFX{Wire}}: \FFX{Ordered collections of edges forming open or closed chains.}
+        \item \textbf{\FFX{Face}}: \FFX{2-dimensional bounded surfaces defined by wires (outer boundaries and holes).}
+        \item \textbf{\FFX{Shell}}: \FFX{Collections of faces forming partial or complete shells.}
+        \item \textbf{\FFX{Solid}}: \FFX{Closed 3-dimensional volumes with definable volumetric properties.}
+        \item \textbf{\FFX{Compound}}: \FFX{Arbitrary aggregates of geometric entities for grouping or assembly construction.}
+    \end{enumerate}
+
+    \item \textbf{\FFX{Coordinate Systems and Working Planes:}} \FFX{ECIP employs a unified coordinate system framework to ensure consistency and precision in geometric modeling and transformation. This framework includes:}
+    \begin{enumerate}[label=\textbf{(\arabic*)}]
+        \item \textbf{\FFX{CoordinateSystem}}: \FFX{Represents a 3D spatial frame with an explicit origin, X-axis direction, and normal vector, providing an abstraction for spatial transformations.}
+        \item \textbf{\FFX{WORLD\_CS}}: \FFX{A global singleton coordinate system instance defining the default reference frame. It follows the right-hand rule with origin at \([0,0,0]\), X-axis pointing forward, Y-axis pointing right, and Z-axis pointing upward.}
+        \item \textbf{\FFX{SimpleWorkplane}}: \FFX{Manages local coordinate systems via context managers, enabling nested coordinate frames with defined origins and orientations. The returned workplane object follows the \texttt{\_wp} naming convention when the variable is not directly referenced within the block, ensuring linter and LLM compatibility. This simplifies relative geometric operations and supports complex modeling workflows.}
+    \end{enumerate}
+
+    \item \textbf{\FFX{Geometry and Semantic Metadata:}} \FFX{ECIP unifies semantic annotation and geometric facts through a lightweight tag--metadata layer implemented in \(\mathtt{TaggedMixin}\). Each entity maintains user-visible tags and structured metadata, while runtime lineage is kept separately to avoid polluting modeling data. This design supports three complementary mechanisms. First, primitive constructors perform geometry-aware auto-tagging: for example, \(\mathtt{make\_box\_rsolid}\) and \(\mathtt{make\_cylinder\_rsolid}\) automatically assign face-level tags such as ``top'', ``bottom'', ``left/right'', and ``side'' based on face normals, edge structure, and primitive type. Second, derived operations use topology tracking to attach semantic tags after modeling edits. ECIP wraps OpenCASCADE builders directly and queries \texttt{Modified()}, \texttt{Generated()}, and \texttt{IsDeleted()} to compute a \(\mathtt{TopoDelta}\), from which result faces are automatically tagged as \texttt{op.cut.generated}, \texttt{op.union.modified}, \texttt{origin.body}, \texttt{origin.tool}, or \texttt{role.section.face}. This avoids brittle index-based bookkeeping and preserves semantic lineage across booleans and feature operations. Third, ECIP stores precise geometric metadata alongside the shape, such as primitive type, box size \((x,y,z)\), cylinder axis and height, sphere center and radius, coordinate-system snapshots, topological references (\(\mathtt{topo\_ref}\)), and compact selector hints (e.g., center, normal, area, length, volume, and bounding box). These metadata are serializable and directly consumable by QL predicates such as \texttt{ql.tag(...)} and \texttt{ql.meta(...)}.}
+
+    \item \textbf{\FFX{Query Language (QL) for Geometric Selection:}} \FFX{SimpleCADAPI provides a dedicated query language module (\texttt{ql}) for declarative geometric selection. QL selectors are fully serializable, enabling transparent logging and replay of selection operations. A selector is constructed by chaining entry-point functions (\texttt{ql.edges()}, \texttt{ql.faces()}, \texttt{ql.wires()}, \texttt{ql.vertices()}), predicates (\texttt{ql.tag()}, \texttt{ql.meta()}, \texttt{ql.curve\_type()}, \texttt{ql.surface\_type()}), ordering keys (\texttt{ql.center\_axis()}, \texttt{ql.geo()}), and cardinality constraints (\texttt{.take(n)}, \texttt{.exactly(n)}). Importantly, QL unifies two complementary selection modes: it can query semantic lineage derived from \(\mathtt{TopoDelta}\)-based tracking, and it can also perform direct geometric selection from shape properties. The integrated example below demonstrates both behaviors within a single workflow.}
+
+\item \textbf{\DP{Example Usage:}}
+\begin{lstlisting}[language=Python]
+from simplecadapi import *
+
+# Create a base solid and attach user metadata
+base = make_box_rsolid(width=12, height=8, depth=4)
+base.add_tag("base_frame")
+base.set_metadata("material", "aluminum")
+
+# Add a local boss in a nested workplane
+with SimpleWorkplane(origin=(0, 0, 4)) as _wp:
+    boss = make_cylinder_rsolid(radius=2.5, height=2)
+
+model = union_rsolidlist(base, boss)[0]
+
+# Drill a through hole; the boolean result carries TopoDelta-based tags/metadata
+tool = make_cylinder_rsolid(radius=1.0, height=6)
+model = cut_rsolidlist(model, tool)[0]
+
+# Semantic selection from topology tracking
+new_cut_faces = (
+    ql.faces()
+    .where(
+        ql.and_(
+            ql.tag("origin.tool"),
+            ql.meta("track.event", "==", "generated"),
+        )
+    )
+    .resolve(model)
+)
+
+# Direct geometric selection without relying on topology order
+top_hole_edge = (
+    ql.edges()
+    .where(ql.curve_type("circle"))
+    .order_by(ql.center_axis("z"), desc=True)
+    .take(1)
+    .exactly(1)
+)
+finished = chamfer_rsolid(model, top_hole_edge, distance=0.5)
+\end{lstlisting}
+\end{itemize}

{simplecadapi-2.0.7 → simplecadapi-2.0.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simplecadapi"
-version = "2.0.7"
+version = "2.0.9"
 description = "A simplified CAD modeling Python API based on CADQuery"
 readme = "README.md"
 license = { file = "LICENSE" }

simplecadapi-2.0.9/rebuttal.md

@@ -0,0 +1,57 @@
+## Rebuttal
+
+### 关于 Critique 1：`SimpleWorkplane` 上下文管理器的使用方式
+
+**我们认可审稿人提出的两点合理关切：**
+
+1. **关于变量命名**：审稿人指出 `as wp` 中的 `wp` 在许多示例中并未被显式使用，这确实不是一个好的示范。我们同意这一观点，并将在后续版本中对不使用返回值的场景统一改为 `as _wp`，以符合 PEP 8 约定并避免给 linter 和 LLM 传递错误信号。这是一个务实的改进，我们完全接受。
+
+2. **关于"上下文空洞"（contextual hole）**：审稿人指出在较大的 `with` 块或分块处理（chunking）场景中，读者/模型可能难以追踪当前工作平面的状态。这是一个有实际意义的可读性担忧，尤其在 LLM 辅助代码生成的场景下确实可能造成困惑。
+
+**我们的设计考量：**
+
+`SimpleWorkplane` 采用上下文管理器模式并非出于"巧妙"的炫技，而是因为它解决了嵌套坐标系管理中的一个实际问题。在 `core.py:205-212` 中：
+
+```python
+def __enter__(self):
+    global _current_cs
+    _current_cs.append(self.cs)  # 压入坐标系栈
+    return self
+
+def __exit__(self, exc_type, exc_val, exc_tb):
+    global _current_cs
+    _current_cs.pop()  # 弹出，无论是否抛出异常
+```
+
+该设计确保了嵌套坐标系的正确组合与自动清理——即使在异常情况下也能保证栈的一致性。我们评估过其他替代方案（如显式的 `push()`/`pop()` 调用），但认为在异常安全性方面上下文管理器是更稳健的选择。
+
+**我们承诺的改进：**
+- 在文档和示例中，对未使用返回值的场景统一使用 `_wp` 命名
+- 在复杂嵌套示例中添加行内注释标注当前工作平面的状态
+- 评估是否在文档中增加一个显式查询当前坐标系的辅助函数（如 `get_current_workplane()`），以减少对上下文作用域的依赖
+
+---
+
+### 关于 Critique 2：`width`/`height`/`depth` 命名 vs. `x`/`y`/`z`
+
+**我们认可审稿人提出的核心关切：**
+
+审稿人指出 `width` 和 `depth` 在不同视角下可能产生歧义，而 `x`/`y`/`z` 是绝对无歧义的。这一点我们部分同意——在没有明确坐标系约定的情况下，"宽度"和"深度"确实可能因观察方向不同而产生混淆。
+
+**我们选择语义化命名的考量：**
+
+1. **领域惯例**：`width`/`height`/`depth` 是 SolidWorks、Fusion 360、FreeCAD 等主流 CAD 软件中创建基本体的标准参数名。我们的 API 目标用户群体是 CAD 工程师，采用其熟悉的术语可以降低学习成本。
+
+2. **在我们的坐标系中歧义是可控的**：SimpleCAD 明确采用 Z-up 右手坐标系（`core.py:25-29`），在此约定下：
+   - `width` → X 方向（向前）
+   - `height` → Y 方向（向右）
+   - `depth` → Z 方向（向上）
+   
+   这个映射在 `operations.py:1016-1021` 的元数据中有显式记录。当用户在 `SimpleWorkplane` 中指定 `normal` 和 `x_dir` 后，局部轴的方向是确定的，语义对应关系也是确定的。
+
+3. **我们已经在 API 中提供了轴向参数**：对于需要精确控制方向的场景，`make_cylinder_rsolid`、`make_cone_rsolid` 等函数接受 `axis` 参数，`make_rectangle_rwire` 接受 `normal` 参数，这些设计已为高级用户提供了轴精确的接口。
+
+**我们承诺的改进：**
+- 在 `make_box_rsolid` 等函数的文档字符串中显式注明 `width → X, height → Y, depth → Z` 的映射关系，消除隐含歧义
+- 评估为 `make_box_rsolid` 等函数增加 `x_size`/`y_size`/`z_size` 作为可选的别名参数（keyword-only），供偏好无歧义命名的用户使用
+- 在文档的"坐标系约定"章节中加强对此映射关系的说明

simplecadapi-2.0.9/refactor-plan/topology-ql.md

@@ -0,0 +1,351 @@
+# Topology QL Design
+
+## Goal
+
+Design a query language that can serve all of the following roles at once:
+
+1. Select sub-topology (`Vertex`, `Edge`, `Wire`, `Face`, `Solid`) during modeling
+2. Be serialized into graph JSON and replayed in another script
+3. Remain understandable enough for GUI / low-code presentation
+4. Be strict enough to detect ambiguous or unstable selections
+
+The key design constraint is that this is **not** just an in-memory filter API.
+It must be a **canonical selection representation** for graph replay.
+
+
+## Core Principle
+
+Runtime object references are useful, but they are not a durable source of truth.
+
+The durable source of truth for selection must be a declarative, serializable,
+graph-aware `SelectionSpec`.
+
+The user may still pass object lists or query helpers ergonomically, but the
+system should normalize all of them into the same canonical selection form.
+
+
+## What QL Must Select
+
+QL must operate over a specific topology universe:
+
+- `vertex`
+- `edge`
+- `wire`
+- `face`
+- `solid`
+
+Each query is evaluated inside a **scope**, not globally. The minimum stable
+scope is a graph node output:
+
+- `source_node_id`
+- `source_output_slot`
+
+Without scope, replay is underspecified.
+
+
+## SelectionSpec
+
+The canonical serialized form should be `SelectionSpec`.
+
+```json
+{
+  "source_node_id": "node_17",
+  "source_output_slot": 0,
+  "target_kind": "edge",
+  "query": {
+    "all": [
+      {"curve_type": "CIRCLE"},
+      {"center_compare": {"axis": "z", "op": "<=", "value": 0.0}}
+    ]
+  },
+  "order_by": [
+    {"center_axis": "z", "desc": false},
+    {"metric": "length", "desc": true}
+  ],
+  "limit": 1,
+  "cardinality": {"exactly": 1},
+  "fallback": {
+    "topo_refs": [...],
+    "indices": [0],
+    "selector_hints": [...]
+  }
+}
+```
+
+### Why this shape
+
+- `query` answers: *what semantic thing are we selecting?*
+- `order_by` answers: *if multiple things match, how are they ranked?*
+- `limit` answers: *how many do we take?*
+- `cardinality` answers: *what count is acceptable?*
+- `fallback` answers: *what do we try when semantic matching is not enough?*
+
+
+## QL Has Three Layers
+
+### 1. Predicate layer
+
+Boolean filters over topology objects.
+
+Examples:
+
+- `tag("face.top")`
+- `meta("track.event", "==", "generated")`
+- `curve_type("circle")`
+- `surface_type("plane")`
+- `metric("length", ">", 5.0)`
+- `center_compare("z", "<", 0.0)`
+- `normal_axis("z", ">", 0.9)`
+
+These must be serializable into an AST.
+
+### 2. Selection layer
+
+Defines target kind, filter, ordering, limit, and cardinality.
+
+Examples:
+
+- `Q.edges().where(...).order_by(...).take(1).exactly(1)`
+- `Q.faces().where(...).take(4).exactly(4)`
+
+This is what should become `SelectionSpec` in graph JSON.
+
+### 3. Graph layer
+
+Connects selection to a specific graph output.
+
+Examples:
+
+- "edges on the output of the node that created the thread body"
+- "faces on the result of the last cut"
+
+The GUI must expose this layer clearly.
+
+
+## Predicate Families
+
+### A. Semantic predicates
+
+These rely on tags and metadata and are the most stable across rebuilds.
+
+- `tag(pattern)`
+- `meta(path, op, value)`
+- `op(name, event="*")`
+- `origin(role)`
+- `role(name)`
+
+These should remain the backbone of stable replay whenever possible.
+
+### B. Geometric type predicates
+
+These identify analytic geometry classes.
+
+- `curve_type("line" | "circle" | "ellipse" | "bspline" | ...)`
+- `surface_type("plane" | "cylinder" | "sphere" | "cone" | "torus" | ... )`
+
+These are necessary for things like selecting cylindrical hole walls or circular
+bottom edges.
+
+### C. Metric predicates
+
+These compare numeric geometric properties.
+
+- `metric("length", op, value)`
+- `metric("area", op, value)`
+- `metric("volume", op, value)`
+- `metric("radius", op, value)`
+- `metric("edge_count", op, value)`
+
+These should support toleranced comparisons eventually.
+
+### D. Positional predicates
+
+These use centers, coordinates, normals, or bounding boxes.
+
+- `center_compare(axis, op, value)`
+- `center_between(axis, min, max)`
+- `normal_axis(axis, op, value)`
+- `bbox_compare(bound, axis, op, value)`
+
+These are essential for "top face", "bottom edge", "left-most face" style
+queries.
+
+### E. Structural predicates
+
+These reason about topology relationships.
+
+- `is_outer_wire()`
+- `is_inner_wire()`
+- `wire_closed(True|False)`
+- `child_of(tag/meta/query)`
+- `parent_kind("face")`
+
+These are important for topology-aware selections beyond raw geometry.
+
+
+## Ordering Is Not Optional
+
+Filtering is not enough. We need deterministic ordering because replay cannot
+trust OCC's iteration order.
+
+Required ordering primitives:
+
+- `order_by(center_axis("z"), desc=False)`
+- `order_by(metric_value("length"), desc=True)`
+- lexicographic multi-key ordering
+
+Ordering is what turns:
+
+> circular bottom edges
+
+into:
+
+> the lowest circular edge, then the largest one, take exactly 1
+
+
+## Cardinality Is Part of the Query
+
+Queries must say not just what to select, but how many are acceptable.
+
+Supported forms should include:
+
+- `exactly(n)`
+- `at_least(n)`
+- `at_most(n)`
+
+Why this matters:
+
+- If replay matches 0 instead of 1, that is usually a hard failure.
+- If replay matches 4 instead of 1, that usually indicates ambiguity.
+- GUI should display cardinality expectations explicitly.
+
+
+## Fallback Strategy Chain
+
+QL is the canonical intent, but replay still needs practical fallback.
+
+Proposed resolution order:
+
+1. Evaluate `SelectionSpec.query` against the replayed scope
+2. Apply `order_by`, `limit`, `cardinality`
+3. If this fails, try stored `topo_ref`
+4. If this fails, try stored `indices`
+5. If this fails, use `selector_hints`
+
+Important: QL should be the **first-class** path, not a late fallback.
+
+
+## What QL Should Not Try To Be
+
+### Not arbitrary Python
+
+This is bad for replay:
+
+```python
+Q.edges().where(lambda e: e.get_length() > 5)
+```
+
+Reason: lambda is not portable or serializable.
+
+### Not kernel-internal topo identity
+
+This is not stable enough to be the primary selection language:
+
+- raw OCC face ids
+- `HashCode`
+- enumeration order
+
+These are valid fallback channels, not canonical query semantics.
+
+
+## Where Current QL Sits
+
+Current implementation already supports a first step toward this design:
+
+- serializable predicates for tag/meta/curve_type/surface_type
+- serializable ordering via `center_axis`
+- serializable selectors via `ShapeSelector`
+- replay path for `fillet/chamfer/shell` using `selection_query`
+
+What is still missing:
+
+- metric predicates
+- richer positional predicates
+- explicit `SelectionSpec` schema with source node scope
+- multi-key ordering
+- formal cardinality beyond `exactly`
+- structural predicates
+
+
+## Why This Matters For Evolve
+
+`evolve` is mostly operation composition, so it is a good fit for graph replay.
+
+The hard part is hidden topology selection like:
+
+```python
+edges = solid.get_edges()
+bottom_edge = edges[:1]
+```
+
+This should become:
+
+```python
+Q.edges()
+ .where(Q.curve_type("circle"))
+ .order_by(Q.center_axis("z"))
+ .take(1)
+ .exactly(1)
+```
+
+This is the exact reason QL should become the canonical selection path.
+
+
+## Incremental Migration Plan
+
+### Phase 1
+
+Already started:
+
+- serializable selectors
+- replay for `fillet/chamfer/shell`
+- first `evolve` migration (`make_threaded_rod_rsolid` bottom chamfer)
+
+### Phase 2
+
+Add geometry metrics and richer positional predicates:
+
+- `metric(name, op, value)`
+- `center_compare(axis, op, value)`
+- `normal_axis(axis, op, value)`
+
+### Phase 3
+
+Introduce formal `SelectionSpec` in graph JSON:
+
+- add source node/output scope
+- make it the canonical serialized selection object
+- keep topo refs / indices / hints as fallback section
+
+### Phase 4
+
+Migrate more hidden selections in `evolve` and other APIs to QL.
+
+### Phase 5
+
+Expose GUI-oriented rendering of selections:
+
+- label
+- source scope
+- target kind
+- cardinality
+- human-readable summary
+
+
+## Practical Rule
+
+If a selection must survive serialization and replay, it should ultimately be
+expressible as QL.
+
+Passing concrete objects should remain ergonomic at the API boundary, but the
+system should normalize them into `SelectionSpec` internally whenever possible.

{simplecadapi-2.0.7 → simplecadapi-2.0.9}/skills/simplecad-self-evolve/SKILL.md

@@ -5,9 +5,9 @@ license: MIT
 compatibility: Requires Python 3.10+, active virtual environment, and network access for package installation.
 metadata:
   project: simplecadapi
-  version: 2.0.7
+  version: 2.0.9
   runtime-package: simplecadapi
-  runtime-spec: simplecadapi==2.0.7
+  runtime-spec: simplecadapi==2.0.9
   cases-module: simplecad_self_evolve_cases
 ---
 
@@ -53,7 +53,7 @@ metadata:
 ## Install behavior
 - Preferred: run `scripts/install.sh` once when skill is installed/activated.
 - Runtime wrappers auto-install on demand if `simplecadapi` is missing.
-- Package installed by default: `simplecadapi==2.0.7`
+- Package installed by default: `simplecadapi==2.0.9`
 - Wrappers install only into a virtual environment interpreter (set `PYTHON_BIN` when needed).
 
 ## Interpreter selection

{simplecadapi-2.0.7 → simplecadapi-2.0.9}/skills/simplecad-self-evolve/references/PROJECT_OVERVIEW.md

@@ -1,8 +1,8 @@
 # Project Overview
 
 - Project: `simplecadapi`
-- Version: `2.0.7`
-- Runtime package: `simplecadapi==2.0.7`
+- Version: `2.0.9`
+- Runtime package: `simplecadapi==2.0.9`
 - Skill cases module: `simplecad_self_evolve_cases`
 
 ## What this skill bundles

{simplecadapi-2.0.7 → simplecadapi-2.0.9}/skills/simplecad-self-evolve/references/PROJECT_README.md

@@ -9,7 +9,7 @@ Experimental scripts and temporary modeling examples are not included as formal
 
 ## Package Installation (Python Package Managers)
 
-Current package name: `simplecadapi`, version: `2.0.7` (see `pyproject.toml`).
+Current package name: `simplecadapi`, version: `2.0.9` (see `pyproject.toml`).
 
 ### Method A: Install from package repository with pip
 
@@ -42,7 +42,7 @@ uv add simplecadapi
 The repository already contains example build artifacts (`dist/`):
 
 ```bash
-pip install dist/simplecadapi-2.0.7-py3-none-any.whl
+pip install dist/simplecadapi-2.0.9-py3-none-any.whl
 ```
 
 If you need to rebuild:

{simplecadapi-2.0.7 → simplecadapi-2.0.9}/skills/simplecad-self-evolve/references/RUNTIME_INSTALL.md

@@ -6,7 +6,7 @@
 PYTHON_BIN=.venv/bin/python scripts/install.sh
 ```
 
-This installs `simplecadapi==2.0.7` to the active Python environment.
+This installs `simplecadapi==2.0.9` to the active Python environment.
 If `PYTHON_BIN` is not set, wrappers default to `python3` (fallback `python`).
 Installation is intentionally blocked for non-venv/system interpreters.