# CADQL Tagging 与 Auto Semantics 重构设计

## 文档状态

- 状态：Partially implemented (bounded transition)
- 目标版本：Semantic Binding Schema 1.0
- 依赖：`design-docs/cadql-brep-query-language.md`
- 目标项目：SimpleCADAPI 2.x
- 主要影响模块：`tagging.py`、`autotag.py`、`core.py`、`topology.py`、`tracking.py`、`graph.py`、`serializer.py`、`cadql/`、各 translator backend
- 非目标：继续扩展当前 `ql.py`、为每种 feature 增加专用 selector、用 tag 替代完整 topology history

### 当前实现边界

当前 2.0 graph/model schema 已实现 Semantic Binding Schema 1.0 的 bounded subset：source-preserving `TagBinding`、`local`/`inherited`/`effective`/`lineage` scope、显式 downward policy、evidence-gated tracking projection、semantic-only graph node、model-level `semantic_bindings` registry 与 strict replay。当前 `ql.py` 仅作为过渡层增加 scoped tag predicate、typed operation/origin/output-role predicate，以及 projected source-binding/source-topology predicate，不是完整 CADQL Query IR。

尚未实现完整 typed CADQL Query IR、完整 Topology Evolution Graph、GraphQL-like parser、所有 topology/use 类型以及全部 translator backend parity。当前实现继续使用 graph/model schema `2.0`；本文中依赖 schema `3.0` 或完整 provider contract 的部分仍为 proposed。

### 已实现的 feature output role 子集

当前 `TopoDelta.roles: Tuple[TopoRoleEntry, ...]` 将 output role 与
`TopoEntry.event` 分开保存。每个 role entry 使用 geometry-node-owned durable
`TopoRef`，并要求 operation-owned OCC witness、`coverage=complete`、
`status=proven` 与 exact result membership。以下是当前 public contract：

| Operation | Role | Kind | Requested cardinality |
| --- | --- | --- | --- |
| Extrude | `extrusion.start` | Face | exactly one |
| Extrude | `extrusion.end` | Face | exactly one |
| Extrude | `extrusion.side` | Face | at least one, bind all |
| Revolve | `revolution.start` | Face | exactly one |
| Revolve | `revolution.end` | Face | exactly one |
| Revolve | `revolution.side` | Face | at least one, bind all |
| Fillet | `fillet.patch` | Face | at least one, bind all |
| Chamfer | `chamfer.patch` | Face | at least one, bind all |
| Shell | `shell.body_face` | Face | at least one, bind all |
| Shell | `shell.offset_face` | Face | at least one, bind all |
| Shell | `shell.closing_descendant` | Face | at least one, bind all |
| Shell | `shell.wall` | Edge | at least one, bind all |
| Loft | `loft.start` | Face | exactly one |
| Loft | `loft.end` | Face | exactly one |
| Loft | `loft.side` | Face | at least one, bind all |
| Sweep | `sweep.start` | Face | exactly one |
| Sweep | `sweep.end` | Face | exactly one |
| Sweep | `sweep.side` | Face | at least one, bind all |

这些 role 由 `FirstShape`、`LastShape`、`Generated`、`Modified`、Fillet/Chamfer
contour API 和 exact result membership 产生；不使用 center/normal、enumeration
 index 或 unmatched-to-generated fallback。Public feature 的 named tag arguments
 lower 为独立 `apply_tag_rselection` node，用户
binding 是 `USER_OPERATION + ASSERTED`，自动 role binding 是
`AUTO_RULE + PROVEN + RECOMPUTE`。Geometry node params 不保存这些 tag。

Strict replay 会重建 feature 后比较 serialized/recomputed role entries，并验证
role allowlist、feature node ownership、output slot、coverage/status、topology
kind、binding ancestry、cardinality 和 exact selected refs。Full revolve 不具有
独立 start/end cap；OCC 未证明的 shell role 也保持 unavailable。调用方请求这些
role 时整个 operation 失败，不以 geometry guess 补齐。

当前 bounded QL 增加：

```python
ql.output_role(role_name="extrusion.end")
ql.source_binding(binding_id="tag_binding_...")
ql.source_topology(topo_id="edge_...")
```

后两个 predicate 只查询 canonical local `TagBinding.evidence`。Extrude 的
source Edge 到 generated side Face 投影只复制完整 witness 下的 local
`USER_OPERATION` binding，并保存 source binding/topology、target topology、
operation、role 和 evidence method。Replay-safe authoring 必须把
`apply_tag_rselection(...)` 返回的 semantic view 作为 feature input；detached
semantic branch 不会引入隐藏 graph coupling。Predicate payload
deserialization 对 unknown kind、unknown/missing fields 与非法 child cardinality
fail closed。

## 1. 摘要

下一代 tagging 系统不再把所有语义压入 topology wrapper 上的 `_tags: set[str]`。Canonical truth 是可序列化、保留来源的 `TagBinding`；CADQL 将 tag 作为 `semantic.tags` 属性查询，并在执行时计算 `local`、`inherited`、`effective` 和 `lineage` 四种 scope。

Auto tagging 也不再表示“给所有结果实体补一些字符串”。它是一组 evidence-gated semantic rules：规则只能在所需事实可证明时产生 `TagBinding`，证据不足时产生 `UNKNOWN`/diagnostic 或不产生 assertion，不能把 unmatched entity 推断为 generated。

本设计遵循以下边界：

1. 用户或产品域赋予的 unary categorical meaning 使用 tag。
2. Current BRep 结构事实使用 topology property/relation。
3. 数值、枚举、几何分类和诊断使用 typed property/metadata。
4. Operation、source role、split/merge/generated/preserved 和多来源因果使用 Topology Evolution Graph。
5. Tag 可以作为稳定意图锚点，但不能成为 relation、history 或 evidence 的损失性副本。

## 2. 当前问题

当前实现由四套机制叠加而成：

| 机制 | 例子 | 当前问题 |
| --- | --- | --- |
| 用户显式 tag | `role.mounting_surface` | 与系统 tag 共用一个 set，无法识别作者和 assignment。 |
| Wrapper 结构 tag | `wire.outer`、`edge.boundary` | 把可直接从 BRep graph 得到的事实 materialize 为字符串。 |
| 几何分类 tag | `face.top`、`face.side` | frame、算法和置信度不明确；未知几何退化为 enumeration index。 |
| Tracking tag | `op.cut.generated`、`origin.tool` | 把 Change event 和 source role 降级为 unary string，且依赖 Face-only matcher。 |

具体缺陷包括：

- `_tags: set[str]` 不保存 assignment、producer、target query、attachment、propagation、evidence 和 lifecycle。
- Downward propagation 直接复制字符串，之后无法区分 local 与 inherited。
- `_carry_source_tags()` 直接复制 source Face 字符串，无法恢复 lineage witness。
- `apply_tracking_tags()` 只遍历 Face，不能消费 Edge/Wire/TopoUse history。
- Unmatched Face 默认被标记 `generated`，把 history 缺失伪装成确定事件。
- Boolean `section_edges` 是 Edge evidence，却用 Face ID 匹配，不能正确工作。
- Loft/sweep 提供 Edge history，但 Face-only auto tagger仍会给结果 Face生成看似完整的 operation tag。
- Transform 的 pure-preserve fallback 没有逐实体 correspondence，却对所有结果 Face声称 preserved。
- `face.face_0`、pattern index 和 sketch edge zip-order 依赖 backend enumeration，不是 durable semantic identity。
- Operation runtime 的 rich `delta_entries` 与 canonical `TopoDelta.entries` 分离，replay/translator 无法保证同一 semantic output。

当前测试中的“每个结果 Face 都有 operation tag”不是正确性证明，因为该覆盖率可以完全由 unmatched-to-generated fallback 产生。

## 3. 与 CADQL 的关系

CADQL 在三种图的联合视图上执行：

| 数据层 | 职责 | Tagging 是否拥有该事实 |
| --- | --- | --- |
| Operation Graph | 模型构建、assignment producer、query binding | 否；TagBinding 引用它。 |
| Current BRep Graph | contains、boundary、incident、adjacent、TopoUse | 否；tag 只作为 entity 的 semantic property。 |
| Topology Evolution Graph | Change input/output、role、event、derivation | 否；lineage scope 依赖它计算。 |
| Semantic Binding Store | 用户/系统声明的稳定 unary meaning | 是。 |

CADQL 只有一种 tag predicate：

```python
cadql.tag("role.mounting_surface", scope="effective")
```

它是对 `semantic.tags` 的 property predicate，不创建新的 selector、anchor 或 context 类型。Tag assignment 的 target 本身使用同一套 `SelectionQuery[T]`；不再引入另一套 tag selector DSL。

## 4. 设计原则

### 4.1 一项事实只有一个 canonical owner

以下映射是强制的：

| 事实 | Canonical owner | 可否派生为 tag |
| --- | --- | --- |
| Face 的 outer/inner loop | `topology.loop_role` | 默认否。 |
| Edge 是 Face boundary | `boundary_uses`/`use_entity` | 否。 |
| Surface 是 plane/cylinder | `geometry.surface_type` | 默认否。 |
| Face 当前在 world +Z 方向 | oriented geometry predicate + frame | 否。 |
| Entity 由某 operation 产生 | `provenance.produced_by` | 否。 |
| Entity 是 preserved/modified/generated | Change output event | 否。 |
| Entity 来自 body/tool/profile/path | Change input role/path | 否。 |
| 用户声明 mounting surface | TagBinding | 是，且这是 canonical truth。 |
| 业务规则证明某面是 sealing surface | TagBinding + rule evidence | 是。 |
| 长度、半径、pattern index | typed property/metadata | 否。 |

Tag materialized cache 可以为性能复制 relation/property 的结果，但必须标记为 derived cache、可丢弃且不能成为 replay truth。Semantic Binding Schema 1.0 不定义此优化。

CADQL 中的 `semantic.role` 和 `semantic.group` 是 registry-backed TagBinding projection，例如从 `role.*` 和 `group.*` bindings 得到结构化视图，不建立第二份 writable storage。`semantic.material` 等具有独立 schema、互斥或结构化值的属性使用 typed semantic property，不同时编码为 tag。查询 provider必须从同一个 canonical owner求值这些属性。

### 4.2 Tag 只表达 unary categorical semantics

适合 tag 的内容：

```text
role.mounting_surface
role.sealing_surface
anchor.datum.primary
group.fasteners
process.inspect
```

不适合 tag 的内容：

```text
op.make_cut_rsolid.generated
origin.tool
face.area.245
edge.index.3
face.normal.+z
wire.outer
```

判断标准：如果完整含义需要 source、target、operation、frame、单位、置信度或多个参与者，它就不是单个 tag。

### 4.3 Evidence 不足时保持未知

Auto semantic rule 的三值结果为：

```text
PROVEN       所需 evidence 完整，允许发出 binding。
NOT_APPLICABLE 规则已完整求值，candidate 不满足。
UNKNOWN      evidence 或 capability 不足，禁止发出 binding。
```

`UNKNOWN` 不能被实现为 false、generated、preserved 或最佳猜测。Strict replay 中，如果 feature 依赖该 auto semantic，`UNKNOWN` 必须产生结构化错误；非依赖型装饰 semantic 可以只生成 diagnostic。

### 4.4 Query intent 与 execution evidence 分离

Target query 描述要标记谁；assignment evidence 描述某次执行为何解析到这些 entities。Replay 先重新执行 query，再比较 evidence。`TopoRef.topo_id` 和 geometry fingerprint 只属于 evidence，不是 TagBinding identity。

### 4.5 Semantic state 是版本化 shape view

`apply_tag_rselection` 不修改 geometry，但产生新的 semantic state version。相同 BRep entity 在 assignment 前后可以有不同 effective tags。CADQL provider 必须相对当前 scope producer/version 读取 bindings，不能从全局 mutable wrapper set 读取历史无关的并集。

## 5. Canonical 数据模型

### 5.1 TagDefinition

Tag token 继续使用 normalized dot-token 格式：

```text
[a-z][a-z0-9_-]*(.[a-z][a-z0-9_-]*)*
```

可选 registry 为已知 namespace 声明行为：

```json
{
  "tag": "role.mounting_surface",
  "namespace": "role",
  "value_kind": "categorical",
  "allowed_target_types": ["face"],
  "default_topology_propagation": "local",
  "default_lineage_policy": "continuation_fragment"
}
```

Registry 用于 validation 和文档，不拥有 assignment。未注册但格式合法的 custom tag 可以被允许，但必须显式提供 propagation 和 lineage policy，不能从字符串前缀静默猜测。

### 5.2 TagBinding

Canonical assignment：

```json
{
  "schema_version": "1.0",
  "binding_id": "tag_binding_mounting_surface",
  "tag": "role.mounting_surface",
  "producer": {
    "kind": "user_operation",
    "node_id": "node_tag_mounting_surface",
    "rule_id": null,
    "rule_version": null
  },
  "scope": {
    "node_id": "node_body",
    "output_slot": 0
  },
  "target": {
    "kind": "selection_query",
    "query_hash": "sha256:...",
    "binding_hash": "sha256:..."
  },
  "attachment": "local",
  "propagation": {
    "topology": "local",
    "lineage": "continuation_fragment"
  },
  "evidence": {
    "kind": "query_execution",
    "execution_hash": "sha256:...",
    "selected_refs": []
  },
  "certainty": "asserted",
  "lifecycle": "assertion"
}
```

字段语义：

| 字段 | Contract |
| --- | --- |
| `binding_id` | Assignment identity，不由 selected topology ID 生成。 |
| `tag` | Unary semantic token。 |
| `producer` | 用户 operation 或 versioned auto rule。 |
| `scope` | Target query 的 current snapshot/version boundary。 |
| `target` | Canonical Query IR binding 或仅用于 legacy import 的 explicit refs。 |
| `attachment` | 新 assignment 只允许 `local`；`inherited` 是计算结果。`effective_legacy` 仅用于迁移。 |
| `propagation.topology` | `local` 或显式 `downward`；`local` 表示不沿 topology传播。 |
| `propagation.lineage` | 允许沿哪些 derivation 计算 lineage visibility。 |
| `evidence` | Assignment execution witness，不参与 query intent hash。 |
| `certainty` | `asserted` 或 `proven`；猜测值不能进入 canonical bindings。 |
| `lifecycle` | replay 时重新解析、重新计算或保持 legacy snapshot。 |

### 5.3 TargetBinding

新 assignment 的 target 必须是：

```text
selection_query   canonical Query IR + runtime bindings
scope_root        lower 为选择当前 scope root 的 canonical query
```

以下 target 只用于迁移：

```text
explicit_refs     execution-local refs，无 semantic intent
legacy_effective  只有旧 flat tag snapshot
```

Auto rule 可以直接在 producer operation 的已知 Change outputs 上产生 target，但 serialization 时仍 lower 为 canonical source-preserving target：

- 引用 producer output variable 的 query；或
- 引用 versioned Change output set 的 internal binding。

不能只保存“当时第 3 个 Face”。

### 5.4 Producer

Producer kind：

```text
user_operation
auto_rule
imported_sidecar
legacy_import
```

Auto rule 必须保存稳定 `rule_id` 和 `rule_version`。修改 rule 语义必须提升 version；replay 可据此检测 semantic drift。

### 5.5 Evidence

Evidence 是 tagged union：

| Kind | 必需内容 | 适用场景 |
| --- | --- | --- |
| `user_assertion` | assignment node、authoring source | 用户明确声明。 |
| `query_execution` | query/binding/execution hash、selected refs | Query target assignment。 |
| `topology_change` | Change IDs、input/output witnesses、coverage | 基于 lineage 的 auto rule。 |
| `geometry_classification` | algorithm/version、frame、tolerance、measured properties | 几何分类规则。 |
| `imported_sidecar` | source URI/hash/schema | 外部 semantic data。 |
| `legacy_snapshot` | imported tags、migration diagnostic | 旧模型兼容。 |

Evidence 可以证明 assignment，但不会把几何 fingerprint 升级为 durable target identity。

## 6. Tag Scope 的正式语义

### 6.1 Local

`local` 返回当前 semantic state version 中，target query 直接匹配该 entity/use 的 bindings。

```text
local(e, v) = {b.tag | binding b is visible in semantic version v
                       AND target(b, v) contains e}
```

它不包含 topology parent、model entity 或 lineage ancestor 的 tag。

### 6.2 Inherited

`inherited` 只来自显式 topology propagation policy：

```text
inherited(e, v) = bindings attached to ancestor a
                  where topology propagation is downward
                  and contains-path(a, e) is valid in snapshot v
```

规则：

- 不再根据 `role.*`、`anchor.*`、`group.*` 前缀自动决定传播。
- Propagation 在 assignment 时显式冻结并序列化。
- Downward 传播计算于 Current BRep containment，不复制字符串。
- 默认是 `local`，即不传播。
- 给 Solid 标记 `role.mounting_plate` 不应默认让每条 Edge 都成为 mounting plate。
- 若确实表达 assembly/model membership，优先使用 model relation 或显式 group binding；不要依靠 topology descendants 模拟产品结构。

### 6.3 Effective

```text
effective(e, v) = local(e, v) union inherited(e, v)
```

`effective` 不自动包含 lineage。这样 current snapshot 内的 attachment semantics 与跨 operation ancestry 保持正交。

### 6.4 Lineage

`lineage` 通过 TagBinding 与 Topology Evolution Graph 联合计算：

```text
lineage(e, v) = source bindings whose tagged entities are reachable
                through allowed Change output derivations
```

默认 policy：

| Policy | 允许 derivation | 说明 |
| --- | --- | --- |
| `none` | 无 | 不跨 operation 可见。 |
| `continuation` | `CONTINUATION` | 只接受同角色延续。 |
| `continuation_fragment` | `CONTINUATION`、`FRAGMENT` | 允许 trim/split fragments。 |
| `explicit` | assignment 指定集合 | 允许 `MERGE`/`REPLACEMENT` 等业务定义。 |

`INTERSECTION` 和 `BOUNDARY` 默认不继承 source tag，因为新 entity 是由 source 参与生成，不等于 source 语义角色的延续。需要选择这类结果时使用 `generated_from`、`depends_on` 或 `cadql.change(...)`。`MERGE`/`REPLACEMENT` 也不默认继承，除非 assignment 显式声明。

`lineage` scope 只返回 lineage-derived tags；调用方若需要本地与 lineage 并集，应显式组合 predicates，不把 `effective` 的含义扩大。

History capability 为 `NONE` 或所需 path evidence 不完整时，请求 `lineage` 必须产生 `UnsupportedQueryCapabilityError`，不能返回空集冒充“没有 tag”。

### 6.5 TopoUse

TagBinding 可以 target entity 或 oriented use：

- Entity tag 对同一 underlying entity 的所有 occurrences 可见。
- TopoUse tag 只对该 parent/orientation/occurrence 可见。
- TopoUse 的 inherited 与 lineage 依赖 use-level containment/evolution evidence。
- 缺少 use ancestry 时不能把 entity lineage tag 冒充 occurrence lineage tag。

## 7. Public API 与 Operation Graph

### 7.1 用户赋值

保留简单入口：

```python
apply_tag(body, "role.mounting_plate")
```

新 schema 中该 convenience API 的固定默认值是：

```text
topology_propagation = LOCAL
lineage_policy = CONTINUATION_FRAGMENT
```

因此它不会把 Solid 的 role 复制给所有 Face/Edge，但在 backend 提供完整 `CONTINUATION`/`FRAGMENT` evidence 时，该 assertion 可以通过 `scope="lineage"` 从后续版本查询。需要 topology downward inheritance 时必须调用带显式 policy 的 `apply_tag_rselection`。迁移期执行旧 model时可以保留旧 effective结果，但新 assignment不能继续按token prefix选择policy。

它 lower 为 scope-root query 和 canonical operation：

```text
apply_tag_rselection(
    scope: Shape<K>,
    targets: SelectionSet<T>,
    tag: Tag,
    topology_propagation: LOCAL | DOWNWARD,
    lineage_policy: NONE | CONTINUATION | CONTINUATION_FRAGMENT | EXPLICIT,
) -> Shape<K>
```

推荐的精确赋值：

```python
mounting_face = (
    cadql.select(cadql.Face, in_=body)
    .where(
        cadql.surface_type.eq("plane")
        & cadql.normal.same_direction_as(
            (0, 0, 1),
            relative_to=body,
            angle_tolerance=cadql.deg(0.1),
        )
    )
    .expect_one()
)

tagged_body = apply_tag_rselection(
    body,
    targets=mounting_face,
    tag="role.mounting_surface",
    topology_propagation="local",
    lineage_policy="continuation_fragment",
)
```

Active `GraphSession` 必须记录 target Query IR 和 binding，不能只记录 resolved Face refs。

### 7.2 读取

CADQL 是 canonical query API：

```python
cadql.select(cadql.Face, in_=body).where(
    cadql.tag("role.mounting_surface", scope="effective")
)
```

`list_tags(shape)` 可以保留为 current wrapper convenience，但默认返回当前 version 的 `effective` tags，并应允许显式 scope：

```python
list_tags(shape, scope="local")
list_tags(shape, scope="effective")
list_tags(shape, scope="lineage")
```

它不得绕过 provider 从 `_tags` 直接读取。迁移期旧签名等价于 `scope="effective"`。

### 7.3 删除和替换

Tag 删除不是从 entity set 中 `discard()` 字符串，而是产生新的 semantic operation，撤销或 supersede 指定 binding：

```text
remove_tag_rselection(scope, targets, tag, matching_producer?) -> Shape<K>
```

默认不能静默删除其他 producer 的同名 binding。例如移除 auto-rule binding 不应删除用户 assertion。

### 7.4 Conflict semantics

同一个 entity 可同时存在多个 producer 的同名 tag，查询结果按 token 去重，但 evidence/projection 保留所有 bindings。

Tag 1.0 不定义基于命名约定的互斥，例如 `state.open` 与 `state.closed`。真正互斥的数据应使用 typed enum property。若产品域 registry 声明 tag group 互斥，assignment validation 必须报告 conflict，不能按“最后写入者获胜”处理。

## 8. Auto Semantics Rule Contract

### 8.1 Rule schema

每条规则必须声明：

```json
{
  "rule_id": "simplecad.primitive.box.face_roles",
  "rule_version": "1.0",
  "trigger": "make_box_rsolid",
  "candidate_type": "face",
  "required_capabilities": [
    "operation_output_roles",
    "oriented_face_geometry"
  ],
  "required_evidence": {
    "history": "operation_native",
    "frame": "operation_context",
    "coverage": "complete"
  },
  "output": {
    "kind": "tag_binding",
    "allowed_tags": ["role.cap.start", "role.cap.end", "role.side"]
  },
  "unknown_policy": "diagnostic",
  "lifecycle": "recompute"
}
```

Rule evaluator 返回：

```text
bindings
status: PROVEN | NOT_APPLICABLE | UNKNOWN
evidence
diagnostics
coverage
```

### 8.2 权威等级

| Level | Source | 可产生的结果 |
| --- | --- | --- |
| 1 | 用户显式 assertion/imported authoritative sidecar | `certainty=asserted` binding。 |
| 2 | Kernel/operation-native topology history | Change graph；满足业务规则时可产生 `certainty=proven` binding。 |
| 3 | Exact current topology fact | topology property/relation；通常不 materialize 为 tag。 |
| 4 | Deterministic geometry classifier | typed geometry property；只有注册业务映射后才能产生 tag。 |
| 5 | Heuristic/fingerprint | diagnostic/evidence only。 |

低等级 evidence 不能覆盖或伪装为高等级事实。尤其 geometry proximity 不能产生 preserved/generated lineage。

### 8.3 Coverage

每个 rule evaluation 必须声明：

```text
COMPLETE    候选 universe 与所需 evidence 完整。
PARTIAL     只有部分 candidates/relations 有 evidence。
NONE        无法求值。
```

只有 `COMPLETE` 且 rule 对具体 candidate 得到 `PROVEN` 时才发出需要全局排他性的 tag，例如“唯一 start cap”。`PARTIAL` 不能通过给其余 candidates 标记 opposite role 来补齐结果。

### 8.4 禁止行为

以下规则在新系统中非法：

- unmatched result entity => `generated`。
- pure-preserve delta => 所有 result entities preserved，而无逐实体 mapping。
- backend enumeration index => semantic tag。
- geometry look-alike => lineage continuation。
- 将 operation 名、event 和 origin role拼接为 tag作为唯一事实。
- 给所有 descendants 无条件复制 `role.*`。
- 多来源 Change => 只保留一个 `origin.*` 字符串。
- rule 失败后静默回退到 fingerprint 并仍标记 `proven`。

## 9. Operation-by-Operation 策略

### 9.1 Primitive

Primitive operation 自己知道构造参数和 output roles，优先使用 operation-native evidence，而不是事后猜测几何。

| 当前输出 | 新 canonical 表达 |
| --- | --- |
| `geom.primitive.box` | `provenance.operation_type == make_box_rsolid` 或 typed semantic metadata，不需要 tag。 |
| 裸 `box` | 删除。 |
| `face.top/bottom/front/...` | 不自动作为 world-direction tag。使用 geometry predicate + explicit frame。 |
| `face.surface` | `geometry.surface_type`。 |

如果产品 API 需要稳定 feature role，可定义 frame-aware operation role：

```text
role.cap.start
role.cap.end
role.side
```

这些角色必须绑定 primitive 的参数方向和 operation context，并保存 rule evidence。对于 box 的四个侧面，如果没有额外业务区别，不自动命名 front/back/left/right；数学对称性应保留为集合。

Cone 必须与 cylinder 使用同一 role contract，不再因为当前实现遗漏 `auto_tag_faces()` 而表现不同。

### 9.2 Extrude 和 Revolve

Feature provenance 和 topology evolution进入 Change graph：

- Profile Face/Coedge 是 `subject` 或 `support` input。
- Start/end continuation、side/boundary outputs使用 event + derivation表示。
- `face.extrusion.start/side/end` 若保留为用户友好 semantic，必须由 operation-native role mapping产生 TagBinding，不使用 center exact equality或 normal exact equality。
- `solid.extrusion` 改为 `provenance.operation_type`，不作为 tag。
- Revolve 使用相同 Change contract；full/partial revolve 的 caps必须按实际 operation evidence处理。

推荐 query：

```python
side_faces = (
    cadql.select(cadql.Face, in_=extruded)
    .where(
        cadql.related(
            cadql.generated_from,
            from_=cadql.this,
            to=profile_boundary,
            derivations=("boundary",),
            depth=1,
        )
    )
)
```

只有业务代码确实需要可命名的 feature role 时才额外发出 `role.extrusion.side`。

### 9.3 Boolean

Boolean 不再产生 canonical `op.*` 或 `origin.*` tags。

必须记录：

- 每个 operand 的 named input port。
- 每个 source entity 的 role：`subject`、`tool`、`support` 或 `context`。
- 每个 output entity 的 event 和 derivation。
- Intersection Edge 的多 source Change witness。

交界 edge 使用：

```python
cadql.change(
    inputs=(
        cadql.change_input(subject_faces, input_port="subjects", role="support"),
        cadql.change_input(tool_faces, input_port="tools", role="tool"),
    ),
    output=cadql.this,
    derivation="intersection",
)
```

不能用 `role.section_face` 替代 Edge-level `INTERSECTION` Change。若产品域确实定义“section interface”业务角色，可在上述 query 上显式应用 tag；该 tag 的 target intent仍是 Change pattern。

多步 cut/intersect 必须保留每一步 Change，不能简单拼接 event buckets 后覆盖相同 `topo_id` 的 `delta_entries`。

### 9.4 Fillet、Chamfer 和 Shell

这些 feature 的核心是 target selection 与 Change graph：

- 用户选择的 Edge/Face 是 `target` input。
- 邻接 support Face 是 `support` input。
- Trimmed source entities 是 `CONTINUATION`/`FRAGMENT` output。
- Transition Face 和新 boundary Edge 是 `BOUNDARY` output。
- 完全消耗的 source entity保留为 historical input与 `DELETED` output event。

默认不产生 `op.fillet.generated` 等 tag。查询 transition geometry 应使用 `generated_from`、`depends_on` 和 `co_result_of`。

用户已有 `role.mounting_surface` 的 source Face，只沿 `CONTINUATION`/`FRAGMENT` 进入 lineage scope；fillet transition Face 不自动继承该角色。

### 9.5 Transform 和 Mirror

Rigid transform 不改变 topology role，但必须提供逐 entity/use `CONTINUATION` mapping。只有 mapping complete 时 lineage tag 才可查询。

- `solid.transform.mirrored` 改为 provenance/operation property。
- 不复制 source wrapper `_tags`。
- Mirror 的 orientation-sensitive TopoUse/normal 必须在新 parent occurrence和 frame中重新求值。
- 没有逐实体 mapping 时 history capability 为 `PARTIAL`，不能把所有 Face声明 preserved。

### 9.6 Loft 和 Sweep

Loft/sweep 必须首先修复 evidence kind mismatch：

- Profile/path Edge history进入 Change graph。
- Result Face/Edge 与 profile/path source的关系必须由 operation-native adapter提供。
- Auto semantic evaluator按 candidate type消费对应 Change outputs，不允许 Face-only fallback。
- Profile 与 path 是不同 input ports/roles，不能把二者 tags union到 result Solid后丢失来源。

如果 backend只能提供 Edge-level partial history，Face lineage query与依赖它的 auto rule必须报告 unsupported/unknown；不能给全部 Faces标记 generated。

### 9.7 Pattern

Pattern 应有显式 Pattern operation 和 instance output relation：

```text
source EntityVersion -> Change(instance identity) -> instance EntityVersion
```

每个 instance 保存稳定 operation-local `instance_key`，index只作为 typed property：

```text
provenance.pattern_instance_key
provenance.pattern_ordinal
```

`solid.pattern.linear/radial` 改为 operation provenance，不是 semantic tag。Source tags通过 `CONTINUATION` lineage policy可见；不要复制到每个 instance wrapper。

对完全对称的 instances，若没有用户 tag或业务 key，CADQL返回集合或 ambiguity，不用 ordinal伪造 semantic identity。

### 9.8 Sketch Promotion

Sketch entity到 BRep Edge的映射是 source binding，不是 tag naming问题：

- Sketch entity/profile使用稳定 semantic refs。
- Promotion adapter记录每个 output Edge对应的 source entity ref和 evidence。
- `sketch.*`、`sketch_profile.*`、`sketch_entity.*` 不再作为唯一 mapping。
- 禁止仅通过 `zip(edges, entity_ids)` 声称 correspondence。
- 用户附着在 sketch entity上的 semantic tag可通过 proven promotion Change在 `lineage` scope查询。

## 10. Topology、Geometry、Provenance 与 Tag 的迁移表

| 现有 tag/数据 | 新位置 | 迁移行为 |
| --- | --- | --- |
| `wire.outer`/`wire.inner` | `topology.loop_role` on WireUse/Coedge | 不导入为 semantic tag。 |
| `edge.boundary` | `boundary_uses` + `use_entity` | 不导入为 semantic tag。 |
| `face.top/bottom/...` | Legacy effective tag；新模型使用 frame-aware geometry query或 explicit role binding | 导入并警告方向语义未声明。 |
| `face.face_N` | Legacy enumeration annotation | 不生成新 binding；仅保留 migration evidence。 |
| `geom.primitive.*` | `provenance.operation_type`/typed metadata | 可保留 legacy effective，不再新发出。 |
| `op.<op>.<event>` | Change output event + performed_by Operation | 不生成新 binding。 |
| `origin.<role>` | Change input role/path | 不生成新 binding。 |
| `solid.boolean.*` | Operation provenance | 不生成新 binding。 |
| `solid.pattern.*` | Pattern provenance/property | 不生成新 binding。 |
| `role.*` 用户 tag | TagBinding | 尽可能恢复 assignment；否则 `effective_legacy`。 |
| `anchor.*` 用户 tag | TagBinding | 同上。 |
| `group.*` 用户 tag | TagBinding 或 model membership relation | 按 domain schema迁移。 |
| Numeric/index tags | typed metadata/property | 不作为 semantic binding。 |

## 11. Legacy 兼容

旧模型只有 flat tags时，导入为：

```json
{
  "producer": {"kind": "legacy_import"},
  "target": {"kind": "legacy_effective", "refs": []},
  "attachment": "effective_legacy",
  "propagation": {"topology": "local", "lineage": "none"},
  "certainty": "asserted",
  "lifecycle": "snapshot",
  "evidence": {"kind": "legacy_snapshot"}
}
```

Provider 只把 `effective_legacy` 暴露给 `scope="effective"`。它不能回答 local、inherited 或 lineage，并产生 migration diagnostic；该 attachment不是正常assignment可写入的值。

兼容规则：

- 旧 public `list_tags()` 继续看到原 effective tokens。
- 旧 QL tag predicate可由 adapter lower 为 CADQL `effective` predicate。
- 不从 token prefix反推旧 propagation。
- 不从 `op.*`/`origin.*` 反向构造可信 Change graph。
- 如果 graph中同时有真实 TopoDelta evidence，可以独立迁移为 Change；仍不能仅依据旧 tag补齐缺失 parent mapping。

## 12. Serialization 与 Provider Contract

Model schema 3.0 增加：

```text
semantic_bindings: TagBinding[]
semantic_rules: AutoSemanticRuleRef[]
semantic_diagnostics: SemanticDiagnostic[]
```

Operation node可以引用其产生的 binding IDs。TagBinding target query复用 model顶层 `query_objects`，不嵌入语义缩水的第二份 query。

Provider 增加：

```python
class SemanticProvider(Protocol):
    def bindings(self, scope_version, entity_or_use) -> Sequence[TagBinding]: ...
    def tags(self, entity_or_use, scope: TagScope) -> Sequence[str]: ...
    def explain_tag(self, entity_or_use, tag: str, scope: TagScope) -> Sequence[TagWitness]: ...
```

`explain_tag()` 至少返回：

```text
binding_id
producer
attachment path
topology inheritance path, if any
lineage Change path, if any
evidence status
diagnostics
```

OCP 和 FreeCAD provider必须运行同一 scope和rule conformance suite。Backend不支持某 rule所需 capability时报告 unknown/unsupported，不自行更换算法。

## 13. Invalidation 与 Replay

TagBinding lifecycle：

| Lifecycle | Replay behavior |
| --- | --- |
| `recompute` | 重跑 target query或auto rule，生成新 evidence并比较 drift。 |
| `assertion` | 重跑 target query；用户 semantic保留，但 query不再满足时失败。 |
| `snapshot` | 仅 legacy/import sidecar；不能声称动态 lineage。 |

参数变化后：

1. 重建 geometry和 Change graph。
2. 重新解析 assignment target query。
3. 重新运行 versioned auto rules。
4. 撤销本次 replay中不再 proven的 derived bindings。
5. 比较旧/新 evidence并生成 drift diagnostic。
6. Feature依赖的 semantic target违反 cardinality时按 CADQL错误模型失败。

Derived auto binding不能因为曾经写入 wrapper set而永久残留。Semantic state由当前有效 bindings重新计算，不执行增量字符串清理猜测。

## 14. 错误与诊断

新增结构化错误：

| Error | 条件 |
| --- | --- |
| `TagValidationError` | token、target type、policy或registry不合法。 |
| `TagTargetResolutionError` | Assignment target query无法满足 cardinality。 |
| `SemanticConflictError` | Registry定义的互斥 semantic同时成立。 |
| `AutoSemanticEvidenceError` | Strict dependency所需rule evidence为UNKNOWN/PARTIAL。 |
| `SemanticCapabilityError` | Provider不能计算请求的tag scope或rule。 |
| `SemanticDriftError` | Strict replay中assignment/rule结果发生不允许的漂移。 |

Diagnostic 至少包含：

```text
binding_id/rule_id
scope version
required and available capability
coverage
candidate count
missing witnesses
repair suggestions
```

## 15. 测试策略

### 15.1 Binding tests

- TagBinding JSON round-trip和stable hash。
- 同名tag、不同producer不会互相覆盖。
- Target query intent与execution refs分离。
- Remove/supersede只影响指定binding。

### 15.2 Scope tests

- local不包含parent和lineage tags。
- inherited只沿显式downward policy计算。
- effective严格等于local union inherited。
- lineage只沿允许的derivations计算。
- `BOUNDARY`/`INTERSECTION` 默认不继承source role tag。
- history缺失时lineage产生capability error而不是空结果。
- entity tag和TopoUse tag保持不同visibility。

### 15.3 Auto rule precision/recall

- 每个emitted binding有required evidence witness。
- 可证明的semantic不会遗漏。
- Unmatched candidate不会得到generated/preserved tag。
- Partial coverage不会产生排他性role。
- Rule version变化产生semantic drift diagnostic。

### 15.4 Operation fixtures

- Primitive roles使用operation frame，不依赖world axis或Face枚举。
- Extrude/revolve caps和sides使用operation-native mapping。
- Boolean interface保留多input Change，Edge evidence不被当作Face。
- Fillet/chamfer source fragments、transition Faces和boundaries可通过evolution relation选择。
- Transform/mirror有逐entity continuation mapping。
- Loft/sweep在只有Edge evidence时拒绝Face lineage assertion。
- Pattern instances保留source lineage和instance key，不以ordinal作为semantic identity。
- Sketch promotion不依赖zip/enumeration order。

### 15.5 Replay与translator

- OCP和FreeCAD的tag scopes一致。
- Model JSON round-trip后producer/evidence/policies不丢失。
- 参数变化后过期auto bindings消失。
- Legacy effective tags仍可查询，但local/inherited/lineage明确unsupported。

## 16. 实施阶段

### Phase A：Characterization 与止损

- 锁定当前public tag行为和serialized fixtures。
- 给unmatched-to-generated、section Edge/Face mismatch、loft/sweep mismatch增加failing characterization tests。
- 停止新增`op.*`、`origin.*`和enumeration-derived tags。
- `apply_tracking_tags()`增加diagnostic mode，逐步取消unsound fallback。

退出标准：所有已知误报都有测试，不再扩大flat-tag contract。

### Phase B：Semantic Binding Schema

- 实现TagBinding、producer、target、policy、evidence和serialization。
- 实现semantic state version与binding store。
- `apply_tag_rselection`记录target Query IR。
- Flat `_tags` 暂时作为effective cache，不再是canonical truth。

退出标准：用户assignment可JSON round-trip并解释来源。

### Phase C：CADQL Scope Provider

- 实现local/inherited/effective。
- 移除prefix-driven runtime copying；迁移为binding-time explicit policy。
- 实现`explain_tag()`。
- Legacy tags仅通过effective adapter暴露。

退出标准：三个current-snapshot scopes通过OCP conformance tests。

### Phase D：Topology Evolution Graph

- 按CADQL设计建立完整Change inputs/outputs。
- 将`delta_entries`合并进canonical序列化schema。
- 修复Face-only consumer、section Edge、transform correspondence和多步Change。
- 实现lineage scope与history capability validation。

退出标准：continuation/fragment/boundary/intersection fixtures可查询且缺证据时失败。

### Phase E：Auto Semantic Rules

- 引入versioned rule registry和三值求值。
- 先迁移primitive与extrude roles，再迁移其他feature。
- 删除unmatched-generated和operation/origin tags的canonical生成。
- Geometry heuristic仅作为typed property或diagnostic。

退出标准：每个auto binding都有rule、evidence、coverage和replay lifecycle。

### Phase F：Translator 与清理

- FreeCAD provider实现相同semantic binding/scope contract。
- 更新docs、skills和examples到CADQL tag query。
- Deprecate `Solid.auto_tag_faces()`和内部直接`_tags`复制。
- 删除flat tag作为truth的代码路径。

退出标准：OCP/FreeCAD semantic conformance一致，新model不依赖flat tags。

## 17. 推荐决策

1. 采用`TagBinding`作为唯一canonical tag assignment；`_tags`只能是迁移期effective cache。
2. Tag仅表达用户/业务域的unary categorical semantics。
3. `wire.outer`、`edge.boundary`迁移到Current BRep properties/relations。
4. `op.*`、`origin.*`、preserved/modified/generated迁移到Operation/Topology Evolution Graph。
5. 几何类型、方向、数值和pattern ordinal迁移到typed properties，不再自动materialize为tag。
6. Downward propagation默认关闭并在每个binding中显式保存；不再按prefix复制字符串。
7. `effective = local union inherited`；lineage保持独立scope并依赖完整Change evidence。
8. Lineage默认只允许`CONTINUATION`/`FRAGMENT`；`BOUNDARY`、`INTERSECTION`、`MERGE`和`REPLACEMENT`不自动继承semantic role。
9. Auto semantics使用versioned、evidence-gated、三值规则；`UNKNOWN`是一等结果。
10. 立即禁止unmatched => generated、enumeration => semantic role、geometry guess => proven history。
11. 所有tag target复用`cadql.select(...)`和Query IR，不建设第二套selector或anchor API。
12. Replay和translator必须保存并解释assignment intent、producer、scope、evidence和drift，不能只搬运最终字符串集合。

这套策略的核心不是让auto tagging覆盖更多实体，而是让每个可查询semantic都有明确作者、目标意图、适用scope、证明依据和失效规则。CADQL负责查询这些事实；Current BRep Graph和Topology Evolution Graph负责证明结构与历史；TagBinding只负责承载真正的semantic assertion。