# ModelDiagnosticVerifier Lessons

This file records diagnosis failures and the rule that prevents repeating them.

## Failure 2026-06-19: `装配体2.SLDASM` was wrongly diagnosed as problem

Context:

- `装配体2.SLDASM` is the textbook `b` pass case for the tight-fit sleeve disassembly rule.
- The correct diagnosis is `pass` because the sleeve has an exposed axial push face, matching image example `b`.

Root cause:

- `SectionBrepExtractor` produced the important feature in `SketchGraph.Dimensions`, not in `SketchGraph.Relations`.
- The verifier consumed section relations but ignored dimension-derived candidates.
- Therefore `external_push_access` stayed incomplete and the final decision became `problem`.

Corrected behavior:

- `SketchGraph.Dimensions` is now read.
- `exposed_sleeve_end_height_candidate` with role `exposed_push_face_candidate` can be promoted to model evidence.
- The promoted evidence satisfies the `b_external_push_access` image 2D structure template.

Promotion rule currently used:

```text
exposed_sleeve_end_height_candidate
+ target sketch edge belongs to a sleeve
+ height is meaningful
=> exposed_axial_push_face
=> outside_accessible_force_path
=> owned_by(push_face, sleeve_material)
=> force_direction_parallel_to_axis(push_face, sleeve_axis)
=> can_push_or_strike(outside, push_face)
=> adjacent_to_outside(push_face, outside)
```

## Rules To Prevent Repeating This Failure

### 1. A model-side 2D structure instance is not only relations

- A model-side 2D structure instance is not only relations.
- It must also consume dimensions, roles, anchors, and candidate annotations when they are produced by the extractor.
- A candidate can be promoted to pass evidence only through an explicit promotion rule.

### 2. Candidate is not failure

Failure pattern:

- Treating an incomplete pass template as absent too early makes the final rule report `problem`.
- In mechanical diagnosis, candidate evidence should remain visible in the result so the missing bridge can be debugged.

Correct rule:

- Keep `candidate`, `found`, and `missing` separate.
- Only final decision uses `found`; debugging output must preserve candidates and missing relations.

### 3. Image template relations must map to model evidence names

Failure pattern:

- Image template requires `external_push_access`.
- Model evidence may expose lower-level facts such as `exposed_sleeve_end_height_candidate`.
- If there is no mapping, the verifier appears to "not understand" a correct model.

Correct rule:

- Every pass evidence type needs a model-evidence promotion path.
- Do not rely only on literal relation name equality.

### 4. Merge duplicate sources before diagnosis

Failure pattern:

- When section evidence and structural evidence are both loaded, the same component or scene can appear twice.
- Duplicate scenes make reports noisy and can mask which evidence actually caused a decision.

Correct rule:

- Merge components by component id.
- Merge scenes by `(sceneType, target, host)`.
- Preserve stronger confidence and union of evidence labels.

### 5. Do not let encoding damage classification

Failure pattern:

- Some older code had mojibake Chinese tokens for component classification.
- Correct Chinese names such as `套筒` can be missed if only garbled tokens remain.

Correct rule:

- Keep component category inference robust:
  - use normal Chinese terms
  - use English aliases
  - prefer metadata from extractors when available
  - avoid depending on name classification when B-rep evidence already identifies owner/category

## Development Checklist For Each New Fault Rule

Before trusting a new rule, check all items below.

- Image side has a semantic rule and at least one image 2D structure template for every pass/problem example.
- Each pass template lists both structure relations and required model evidence.
- Every required model evidence item has a documented extraction or promotion path.
- The model verifier consumes all extractor layers used by that path: components, contacts, section edges, section relations, dimensions, regions, roles, and annotations.
- The report shows `found`, `candidate`, and `missing` for both model evidence and 2D structure relations.
- Known positive and known negative examples are tested before generalizing the rule.
- A `problem` result is not accepted until the missing evidence chain has been inspected.